Troubleshoot system and 5xx error codes

The generic system codes — INTERNAL_ERROR, BAD_GATEWAY, UPSTREAM_ERROR, UNPROCESSABLE_ENTITY, INVARIANT_VIOLATION, MISSING_TENANT, and TENANT_NOT_FOUND — surface on requests that failed before the caller’s domain logic could run. They read as opaque platform failures, but most split into two clear classes: transient (safe to retry) and deterministic (retrying changes nothing — fix the request or escalate). This page tells you which class a code belongs to and what to do about it.

Step 1 — read the retry-safety flag on the envelope

Before you classify anything, look at the error envelope you got back. Each response carries an error object with code, message, status, and optional details, plus a meta block with request_id and docs_url:

{
  "error": {
    "code": "UPSTREAM_ERROR",
    "message": "The upstream provider is temporarily unavailable",
    "status": 502,
    "details": {
      "retryable": true,
      "retry_after_seconds": 2
    }
  },
  "meta": {
    "request_id": "req_9e4c71",
    "timestamp": "2026-09-09T14:02:11Z",
    "docs_url": "https://docs.orbit.devotel.io/errors/UPSTREAM_ERROR"
  }
}

Two opt-in fields decide whether you retry:

details.retryable: when a transient class of failure is identified before the response is built, the envelope is stamped "retryable": true. That marks the response as designedly safe to retry — the platform has deliberately classified this failure as an availability blip, not a fault.
details.retry_after_seconds: when the envelope also names a wait window, the response carries it both in details and as a standard Retry-After header. Honour that window before retrying instead of retrying immediately.

If neither field is present, fall back to the default assumptions in the table below. In either case, keep the meta.request_id — it is the handle support uses to trace the failure if you escalate.

One well-known transient class, TENANT_SCHEMA_INCOMPLETE, has its own runbook at Troubleshoot TENANT_SCHEMA_INCOMPLETE (503). Check for that code before treating a 503 as generic.

Step 2 — classify the code

The table below lists the system codes as they appear in responses. The status field on a response is always authoritative for that response — where a code can surface under more than one status, the table names the value you most commonly see.

Code	Typical status	Class	What it means	What to do
`INTERNAL_ERROR`	500	Platform fault	The platform failed to complete the request; the message has been sanitized so it contains no internal detail.	Retry once, only if the operation is safe to repeat — send a mutation again only when it is already idempotent (a read, or a write at an endpoint that accepts `Idempotency-Key`), and always with a fresh `Idempotency-Key`. Repeating a blind retry loop will not clear a genuine platform fault.
`UPSTREAM_ERROR`	502	Transient	A provider the platform needed (carrier, email relay, AI provider, storage) timed out or returned an error mid-request, so the platform had to abort.	Check the status page first — if provider outages cluster, work is queued until the provider recovers. If not, retry with backoff.
`BAD_GATEWAY`	502	Transient	The platform-side edge (the gateway layer that fronts the API) failed to reach the backend that serves your request.	Same as `UPSTREAM_ERROR` — check the status page, then retry with backoff.
`UNPROCESSABLE_ENTITY`	422	Deterministic	The request passed syntax but failed domain validation (a value the recipient, sender, or policy objects to). This is tenant-owned: it is telling you the payload is wrong for the account data or policy, not that the platform failed.	Do not retry the same body. Fix the field named in `details` and send the corrected request. Retrying the same payload returns the same 422 forever.
`INVARIANT_VIOLATION`	500	Platform guard-trip	The platform’s consistent-state guard rejected your request: something about the call would have violated a rule the platform enforces to keep its own state coherent (for example, an out-of-order state transition on a resource). This almost always means a bug the platform should not have produced.	Report to support immediately — do not retry; the same guard will trip again. Include `meta.request_id` and the request payload that triggered it.
`MISSING_TENANT` / `TENANT_NOT_FOUND`	400 / 404	Caller-fixable	The tenant-context gate could not attach your request to an organization. The API key resolved, but the resolved organization is missing or no longer provisioned.	Fix the credential first — check that you are addressing the right organization and key mode (live vs. sandbox). Do not retry until the key resolves cleanly. If the same key worked yesterday and fails today, escalate — something on the account has been removed.

UNPROCESSABLE_ENTITY and VALIDATION_ERROR are both 422 determinants — match on the response code, not the message text. Either way, the fix is in your payload, not in a retry.

Step 3 — the decision checklist

Walk these steps in order on any of the codes above:

Read the envelope. Capture error.code, error.status, and meta.request_id.
Status page. For UPSTREAM_ERROR or BAD_GATEWAY, check status.orbit.devotel.io before you retry or escalate — an active incident answers every question.
Retry or fix. Retry only when the envelope says retryable: true, or the operation is a read, or it accepts a fresh Idempotency-Key and you supply one. For a deterministic code (UNPROCESSABLE_ENTITY, MISSING_TENANT, TENANT_NOT_FOUND), fix the request and move on.
Escalate. If a retryable check, a payload fix, and one retry all return the same code, or the code is INTERNAL_ERROR or INVARIANT_VIOLATION, open a support ticket.

Worked examples

A transient 503 stamped safe by the platform — the designed retryable envelope you should pass straight through your retry loop:

{
  "error": {
    "code": "UPSTREAM_ERROR",
    "message": "Email provider temporarily unavailable",
    "status": 503,
    "details": {
      "retryable": true,
      "retry_after_seconds": 3
    }
  },
  "meta": {
    "request_id": "req_9e4c72",
    "timestamp": "2026-09-09T14:02:11Z",
    "docs_url": "https://docs.orbit.devotel.io/errors/UPSTREAM_ERROR"
  }
}

A deterministic 422 the platform will keep returning until the payload is fixed:

{
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "Sender ID violates the destination format rules",
    "status": 422,
    "details": {
      "field": "from",
      "value": "ORBIT-SALES"
    }
  },
  "meta": {
    "request_id": "req_9e4c73",
    "timestamp": "2026-09-09T14:02:11Z",
    "docs_url": "https://docs.orbit.devotel.io/errors/UNPROCESSABLE_ENTITY"
  }
}

A 500 that should not be retried — escalate with meta.request_id:

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Unexpected platform failure",
    "status": 500
  },
  "meta": {
    "request_id": "req_9e4c74",
    "timestamp": "2026-09-09T14:02:11Z",
    "docs_url": "https://docs.orbit.devotel.io/errors/INTERNAL_ERROR"
  }
}

Escalation

Open a support ticket when any of these holds:

The status page shows no incident, yet UPSTREAM_ERROR or BAD_GATEWAY persists past a few minutes of backoff.
The response says retryable: true and you have already retried within the stated window, but the same failure returns.
The code is INVARIANT_VIOLATION or INTERNAL_ERROR — both name the platform.
The code is MISSING_TENANT / TENANT_NOT_FOUND and a working key suddenly stops resolving its organization.

Include the meta.request_id, the payload body (minus any credentials), and whether the failure is reproducible or intermittent.

Reference

Troubleshoot system and 5xx error codes

Troubleshoot system and 5xx error codes

Step 1 — read the retry-safety flag on the envelope

Step 2 — classify the code

Step 3 — the decision checklist

Worked examples

Escalation

See also

​Troubleshoot system and 5xx error codes

​Step 1 — read the retry-safety flag on the envelope

​Step 2 — classify the code

​Step 3 — the decision checklist

​Worked examples

​Escalation

​See also

Troubleshoot system and 5xx error codes

Step 1 — read the retry-safety flag on the envelope

Step 2 — classify the code

Step 3 — the decision checklist

Worked examples

Escalation

See also