Skip to main content

​
Troubleshoot TENANT_SCHEMA_INCOMPLETE (503)

Orbit keeps every organization in its own tenant schema. When your API key resolves to an org whose schema is still provisioning — or whose table set is mid-migration during a rollout — a request that would have to read that schema fails fast with 503 and code TENANT_SCHEMA_INCOMPLETE, with the message Tenant database temporarily unavailable. Nothing is charged and nothing is written. This is not an auth failure. Your API key resolved correctly — the 503 comes after the key is accepted, when the platform attaches the request to your org’s schema and finds it incomplete. Do not rotate your API key in response to this error; a fresh key resolves to the same org and hits the same window.

​
Expected duration

Provisioning completes in seconds. The platform builds your schema with the full base table set at org creation, so a 503 raised during onboarding clears on a retry moments later without any action from you. During a migration rollout, a tenant can briefly sit in a window where a table or column a route expects has not landed yet in its schema. Read-only dashboard endpoints degrade gracefully in that window — they return an empty 200 payload instead of a 503, so a dashboard poll keeps working. Write and action endpoints that cannot safely degrade return the structured 503 instead, then succeed once the window closes.

​
When it persists longer

Two automatic repair loops close a gap that survives the first minutes:
  1. Request-time self-heal. If your org’s readiness flag never flipped to ready, the next authenticated request repairs the schema in-band before the route runs. One retry is usually enough to clear it.
  2. The 15-minute repair sweep. If the org is flagged ready but the schema itself is missing or incomplete, a background sweep re-detects the gap every 15 minutes and replays it. This is the loop that catches orphaned provisioning failures.
Either loop closes the condition without a support ticket.

​
What to do

  1. Retry with a short backoff. Treat this 503 as transient: wait a few seconds, retry, and extend the gap geometrically if it repeats. Unlike a 402 billing rejection, which is terminal until the wallet is funded (see INSUFFICIENT_BALANCE), this class resolves on its own.
  2. Match on the code, not the message. Integrate on TENANT_SCHEMA_INCOMPLETE; the Tenant database temporarily unavailable message text is not a stability contract.
  3. Escalate after an hour. If the same 503 persists past an hour, open a support ticket with your organization ID (dashboard → Settings → Organization; also organizationId from GET /api/v1/me) and the request ID of one failing call.
Do not pass tenant_id in your request input to work around this error. It is ignored — the platform resolves the tenant from your API key on the server side, and that server-side resolution is the tenant-isolation control our SOC 2 posture is built on (tenant isolation, Section 4). A client-supplied tenant_id cannot point the request at another schema, ever.

​
For resellers

Sibling subaccounts under one parent org share the parent’s tenant schema (the subaccount model, Section 3). A subaccount that hits TENANT_SCHEMA_INCOMPLETE is seeing the parent’s schema mid-window, not a per-subaccount fault — one repair heals the whole org family, and every sibling clears at the same time. Escalate once per org family, not per subaccount.

​
See also

  • Tenant isolation — provisioning and the migration window (Section 2.1), how the API resolves tenant on every request (Section 4), and the per-request tenant connection (Section 4.1)
  • UCaaS, CCaaS, and CPaaS auth model — how the API key resolves to one org before any tenant attachment runs
  • Rate limits — the 429 cousin: also transient and safe to retry, but for throughput, not schema state
  • Insufficient balance — the 402 terminal counterpart for contrast on retry behavior
  • Error codes reference — the full code list