> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting: API_HOST_RETIRED (410) on a legacy API host

> Resolve the 410 API_HOST_RETIRED rejection — the platform guard that answers any request addressed to the retired pre-cutover API host with the canonical base URL, and the migration steps for each surface (SDK, redirect/LB, environment variables).

# Troubleshooting: API\_HOST\_RETIRED (410) on a legacy API host

The Orbit API answers **one** canonical host: `https://api.orbit.devotel.io`.
The pre-cutover host `orbit-api.devotel.io` was retired on 2026-06-03. Any
request that still arrives on the retired host is answered at the edge of the
API process — before CORS, before authentication, before routing — with:

```json theme={null}
{
  "error": {
    "code": "API_HOST_RETIRED",
    "message": "The host orbit-api.devotel.io was retired on 2026-06-03. Use https://api.orbit.devotel.io instead.",
    "status": 410
  },
  "meta": {
    "request_id": "…",
    "timestamp": "…",
    "canonical_host": "api.orbit.devotel.io"
  }
}
```

The 410 envelope also carries `Deprecation: true` and a
`Link: <https://api.orbit.devotel.io>; rel="successor-version"` header, so a
well-behaved HTTP client surfaces the successor host even before you read the
body.

<Note>
  A 410 here is not a fault and not an availability problem — it is the
  platform's deliberately loud retirement signal. The retired host must stay
  dead: it shares its load-balancer IP with the canonical host, so an ingress
  regression would otherwise silently revive it. The guard lives in the
  application itself precisely so a mis-configured ingress cannot undo the
  retirement.
</Note>

## What API\_HOST\_RETIRED means

The retired-host guard is the first plugin in the API's request pipeline. It
matches the request's Host header (port-stripped, case-insensitive) against
the retired hostname, short-circuits if it matches, and leaves every other
host untouched. The runbook for the full pipeline — where this guard sits
relative to authentication, rate limits, and idempotency — is the
[API request guard pipeline](/concepts/api-request-guard-pipeline) concept
page.

Because the guard answers **before authentication**, an `API_HOST_RETIRED`
response carries no information about your API key or workspace — the request
was never authenticated. Fix the base URL, then re-check for a real
authentication response.

## Migration steps

Work the surfaces in order — SDK clients first, then anything you front the
API with, then environment-driven configuration:

1. **SDK configuration.** Find where the client is initialized and point the
   base URL at the canonical host. For the Node SDK the override is the
   `baseUrl` option; for raw HTTP it is whatever constant your code names the
   URL ("API\_BASE\_URL", "ORBIT\_API\_URL", etc.):

   ```ts theme={null}
   import { Orbit } from "@devotel/sdk-node";
   const orbit = new Orbit({
     apiKey: process.env.DEVOTEL_API_KEY,
     baseUrl: "https://api.orbit.devotel.io",
   });
   ```

   The SDKs default to the canonical host, so an explicit `baseUrl` that
   still names `orbit-api.devotel.io` is the stale value to replace.

2. **Redirect / load balancer.** If you front the API with your own reverse
   proxy or API gateway, or you re-export a webhook receiver URL that another
   system calls, update the upstream target to the canonical host. A 301/308
   redirect at your edge is brittle here — `fetch` follows redirects, so a
   mis-pointed integration would appear to work while still depending on the
   retired name. Point the upstream at the canonical host directly.

3. **Environment variables.** Grep your deploys for the retired hostname.
   Common containers: `ORBIT_API_URL`, `DEVOTEL_API_BASE_URL`,
   `API_BASE_URL`, and webhook receiver URLs that construct the API endpoint
   from a base variable. Update the variable in every environment (including
   CI secrets and partner-shared .env examples), then redeploy.

<Warning>
  Do not wait for the retired host to stop answering before you migrate. It is
  kept dead deliberately; relying on it is a misconfiguration, not a grace
  period.
</Warning>

## Verification

Confirm the handshake against the canonical host:

```bash theme={null}
curl -sS -o /dev/null -w "%{http_code}\n" \
  https://api.orbit.devotel.io/health
```

A `200` (any non-410 status for an authenticated probe) means the base-URL
fix landed. Then repeat the original failing call against the canonical host
and confirm you get a real response — `401` at worst, which moves you into
the [authentication and IP allowlist](/troubleshooting/auth-and-api-keys)
runbook.

## What to send support

If you still get `API_HOST_RETIRED` after the base-URL fix, open a ticket with:

* The exact **Host** your request is addressed to (copy it from your
  client logs or a `curl -v` trace — scheme and path do not matter, only the
  host).
* The **request\_id** from the error envelope's `meta.request_id`.
* Which surface you fixed (SDK config, proxy upstream, or env var) and the
  deploy it shipped in.

## See also

* [API request guard pipeline](/concepts/api-request-guard-pipeline) — where
  the retired-host guard sits in the full request chain and why the 410
  fires before every other gate.
* [Authentication and IP allowlist](/troubleshooting/auth-and-api-keys) —
  the next failure you will see once the base URL is fixed.
* [Error codes reference](/reference/error-codes) — the full error catalog
  and envelope shapes.