Skip to main content

​
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:
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.
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.

​
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 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.):
    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.
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.

​
Verification

Confirm the handshake against the canonical host:
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 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