> ## 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.

# Troubleshoot TENANT_SCHEMA_INCOMPLETE (503)

> One recovery path for 503 TENANT_SCHEMA_INCOMPLETE / 'Tenant database temporarily unavailable': why the platform returns it during provisioning or a migration rollout, how long it lasts, which repair loops close it, and what never to do.

# 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](/troubleshooting/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.

<Warning>
  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](/concepts/tenant-isolation), Section 4). A client-supplied
  `tenant_id` cannot point the request at another schema, ever.
</Warning>

## For resellers

Sibling subaccounts under one parent org share the parent's tenant schema
(the [subaccount model](/concepts/tenant-isolation), 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](/concepts/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](/concepts/ucaas-ccaas-cpaas) — how the
  API key resolves to one org before any tenant attachment runs
* [Rate limits](/troubleshooting/rate-limits) — the `429` cousin: also
  transient and safe to retry, but for throughput, not schema state
* [Insufficient balance](/troubleshooting/insufficient-balance) — the `402`
  terminal counterpart for contrast on retry behavior
* [Error codes reference](/reference/error-codes) — the full code list