Skip to main content

​
Troubleshoot tenant provisioning lifecycle codes

Orbit attaches every authenticated request to your organization’s tenant context before any route runs. When that attachment cannot resolve a usable tenant, the pre-flight gate rejects the request with one of four lifecycle codes — and nothing downstream executes. This page is the recovery hub for the full ladder. Scope it before you escalate: a 400 MISSING_TENANT, a 404 TENANT_NOT_FOUND, and a 503 TENANT_PROVISIONING all mean different things, and the one code that names schema drift — TENANT_SCHEMA_INCOMPLETE — has its own dedicated runbook.

​
The lifecycle ladder

Every organization walks this ladder from signup to steady state. A lifecycle code tells you exactly where on the ladder the request died:
  1. MISSING_TENANT (400) — the request carried no resolvable tenant context at all (no API key header, or an X-Tenant-Id-based call with the header absent). Attachment never started.
  2. TENANT_NOT_FOUND (404) — the request authenticated, but the resolved tenant context points at an organization record that does not exist. Attachment started and looked up nobody.
  3. TENANT_PROVISIONING (503) — the organization record exists, but its tenant data store is still being initialized (or a stuck initialization is queued for the background repair sweep). Attachment found the org and found its tenant context not yet ready.
  4. TENANT_SCHEMA_INCOMPLETE (503) — the tenant context is attached, but a recently added table migrates in during a rollout — follow the dedicated runbook for this one code.
  5. Resolved — the ladder’s steady state: the gate passes and the route runs.
Codes 1–3 got rejected at the pre-flight gate, so nothing is charged and nothing is written in any of them.

​
Detection

Reproduce with a header-selected request against any tenant-scoped resource so you can read the raw status split yourself — the 503-vs-404-vs-400 difference is the whole diagnosis:
Pick the most lightweight tenant-scoped resource your integration already calls (GET /api/v1/messages, GET /api/v1/contacts) so the reproduction costs nothing. Read the error.code field of the response — do not parse the message text:
A 400 narrows to the first rung; a 404 narrows to the second; a 503 narrows to a provisioning or schema window. That split, plus the envelope’s meta.request_id, is what to hand to support.

​
Fix per code

​
MISSING_TENANT (400)

The request never authenticated to a tenant. Send a valid API key (X-API-Key: dv_live_sk_...) on API-key flows, or add the X-Tenant-Id: <organizationId> header on internal-header flows. If you see this after the API key resolved (rare), one header consumer in the chain (access-token exchange, a chained voice/provider hop) dropped the context — reproduce with the detection curl above and escalate with one meta.request_id.

​
TENANT_NOT_FOUND (404)

The org-level tenant record itself is absent. The two buggy paths that produce this are a staging window in invited-org onboarding (an invitation accepts before the org row commits) or a race condition on sub-org creation (two sibling orgs created concurrently, one row landed incompletely). If you created the account in the last hour, retry once after a minute. If it persists, stop retrying and capture the reproduction curl. On the platform side, Orbit’s internal operations team resolves this at the organization record (Admin Panel → Org → Tenants) — either the row exists with a wrong tenant reference (repairable in place) or it genuinely does not exist and onboarding must re-run. The operation concludes with a recovery scan, a scheduled sweep that re-detects rows whose tenant reference is missing and queues them for repair. With a paid plan on file, open a support ticket with your organizationId (dashboard → Settings → Organization) and one failing meta.request_id; support routes it to that recovery operation.

​
TENANT_PROVISIONING (503)

The org exists, but its tenant context is still being initialized. This is a transient gate: provisioning completes in seconds during onboarding, and when initialization gets stuck (or the request races initialization under a lock), a background repair sweep re-detects the gap every 15 minutes and replays it. Unlike INSUFFICIENT_BALANCE (402, terminal until funded), retry with exponential backoff — the window closes on its own. Do not rotate your API key: the key resolved correctly; the 503 fires after resolution, when attachment finds the context not yet ready. Escalate only if the same 503 survives past an hour.

​
TENANT_SCHEMA_INCOMPLETE (503)

A dedicated runbook covers this one — schema drift during a rollout, its expected duration, and why read endpoints degrade to an empty 200 while write endpoints 503. See Troubleshoot TENANT_SCHEMA_INCOMPLETE (503).
Do not pass a tenant_id field in a request body to work around any of these codes. Server-side tenant resolution derives the context from your API key or session, and that server-side resolution is the tenant-isolation control Orbit’s SOC 2 posture is built on (tenant isolation, Section 4). Client-supplied tenant fields are ignored and cannot point a request at a different context.