API error handling by example

Every Orbit API error returns the same envelope: a machine-readable code, a human-readable message, the HTTP status, and contextual details, plus a meta.docs_url that links straight to the error’s remedy. This guide walks that envelope, works through three real failures end to end, and gives you a retriable-vs-terminal decision table so your integration handles errors the same way every time. For the full code list, see the Error Code Reference. For codes by domain with remediation notes, see Error Codes.

1. The error envelope

A failed request returns the same JSON shape regardless of which endpoint rejected it:

{
  "error": {
    "code": "INVALID_PHONE_NUMBER",
    "message": "The 'to' field must be a valid E.164 phone number",
    "status": 422,
    "details": {
      "field": "to",
      "value": "+1234",
      "expected": "E.164 format e.g. +14155552671"
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-03-08T00:00:00Z",
    "docs_url": "https://docs.orbit.devotel.io/errors/INVALID_PHONE_NUMBER"
  }
}

Read it in this order:

Field	What it tells you	What to do with it
`error.code`	The stable, retry/consume decision key (e.g. `RATE_LIMITED`, `FREQUENCY_CAP_EXCEEDED`).	Branch on this. Never parse `message` — wording can change; the code does not.
`error.message`	A human-readable explanation of this rejection.	Log it; show it to operators, not to end users.
`error.status`	The HTTP status as an integer (422, 429, 503, …).	Use it for coarse routing when no finer branch applies.
`error.details`	Structured context for the failure — which field failed, which rule fired, how long to wait.	Read the sub-field that names the fix: `details.field` for validation errors, `details.retry_after_seconds` for caps and throttles.
`meta.request_id`	The server’s correlation id for this request.	Include it when you open a support case — it ties to the platform’s server-side log.
`meta.docs_url`	A docs link specific to this error code.	Surface it in developer tooling; it resolves to the code’s anchor on the reference page.

Two shape notes that matter in code:

details is optional. Legacy and triage envelopes may omit it — always guard details?.field rather than assuming the key exists.
429 bodies are self-describing. A rate-limited response carries the back-off hint inside the envelope (error.retry_after on the global limiter, details.retry_after_seconds on caps) and as a Retry-After header — read whichever your HTTP client exposes.

2. Three worked failures with the fix in code

(a) `INVALID_PHONE_NUMBER` — a non-E.164 `to` on an SMS send

Sending to a number that isn’t E.164 (a bare digit string, a local-format number) is rejected with HTTP 422 before anything dispatches:

curl -X POST https://api.orbit.devotel.io/api/v1/messages \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "to": "+1234",
    "body": "Your order shipped."
  }'

{
  "error": {
    "code": "INVALID_PHONE_NUMBER",
    "message": "The 'to' field must be a valid E.164 phone number",
    "status": 422,
    "details": {
      "field": "to",
      "value": "+1234",
      "expected": "E.164 format e.g. +14155552671"
    }
  }
}

This is a terminal, caller-fixable error — retrying the same body returns the same 422. The fix is to normalize the destination into E.164 (+{country-code}{national-number}, no spaces or dashes) and resend:

curl -X POST https://api.orbit.devotel.io/api/v1/messages \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "to": "+14155552671",
    "body": "Your order shipped."
  }'

In code, treat INVALID_PHONE_NUMBER as a validation failure to correct, not a send failure to retry:

if (err.code === "INVALID_PHONE_NUMBER") {
  // Terminal: fix the input, don't retry the same payload.
  markRecipientInvalid(err.details?.field, err.details?.value);
  return { sent: false, reason: "invalid_number" };
}

The same handling covers INVALID_FROM_NUMBER (the from side) and INVALID_RECIPIENT — all three mean “the number shape is wrong for this send,” never a transient provider hiccup.

(b) `RATE_LIMITED` 429 — read `Retry-After`, back off exponentially

When your request rate exceeds the global limiter, Orbit answers with HTTP 429 and a body that tells you exactly how long to wait:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 4 seconds.",
    "status": 429,
    "retry_after": 4
  },
  "meta": { "request_id": "req_xyz789", "timestamp": "2026-03-08T00:01:12Z", "docs_url": "https://docs.orbit.devotel.io/errors/RATE_LIMITED" }
}

The response also carries a Retry-After: 4 header. Honor it before any exponential fallback — the server-set value reflects the actual bucket refill time, so a blind doubling may retry too soon (and re-429). Node retry wrapper:

async function sendWithRetry(
  fn: () => Promise<Response>,
  maxAttempts = 5,
): Promise<Response> {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const res = await fn();
    if (res.status !== 429) return res;

    const body = await res.clone().json().catch(() => ({}));
    const retryAfterSeconds =
      Number(res.headers.get("Retry-After")) ||
      Number(body?.error?.retry_after) ||
      Math.min(2 ** (attempt - 1), 32); // capped exponential fallback: 1s, 2s, 4s, …

    if (attempt === maxAttempts) return res;
    await new Promise((r) => setTimeout(r, retryAfterSeconds * 1000));
  }
  throw new Error("unreachable");
}

Python retry wrapper:

import time

def send_with_retry(fn, max_attempts=5):
    for attempt in range(1, max_attempts + 1):
        res = fn()
        if res.status_code != 429:
            return res

        retry_after = res.headers.get("Retry-After")
        if retry_after is None:
            try:
                retry_after = res.json()["error"]["retry_after"]
            except (ValueError, KeyError):
                retry_after = min(2 ** (attempt - 1), 32)  # capped exponential fallback

        if attempt == max_attempts:
            return res
        time.sleep(float(retry_after))
    raise RuntimeError("unreachable")

Prefer the server’s retry_after over your own doubling whenever it’s present — the limiter knows when its window opens; your client doesn’t.

(c) `FREQUENCY_CAP_EXCEEDED` — skip the recipient, don’t fail the batch

A frequency cap you configured (Settings → Frequency caps, or the Frequency Caps API) rejects an over-cap direct send with HTTP 429 and a details block naming the exact rule that fired:

{
  "error": {
    "code": "FREQUENCY_CAP_EXCEEDED",
    "message": "Send blocked by a frequency-cap rule for this recipient and channel. Try again later or raise the cap in Settings → Frequency caps.",
    "status": 429,
    "details": {
      "channel": "sms",
      "window_seconds": 86400,
      "max_count": 3,
      "cap_id": "fc_9Qx2...",
      "retry_after_seconds": 4180
    }
  }
}

This is skip-not-fail: the recipient is over their allowance, not erroring. The correct handling is to defer that one recipient and move on:

if (err.code === "FREQUENCY_CAP_EXCEEDED") {
  const deferSeconds = err.details?.retry_after_seconds ?? 3600;
  deferRecipient(recipient, deferSeconds); // re-queue after the window, don't drop
  continue; // next recipient — do not abort the batch
}

Two rules that keep this cheap:

Never re-POST immediately. A capped recipient 429s again until retry_after_seconds elapses — an immediate retry just burns an API call. Wait the server-provided retry_after_seconds, not a fixed backoff: the oldest in-window send ages out then, and the slot reopens.
Batch sends skip by design. Campaign and drip sends don’t 429 per recipient — the capped recipient reports status: "skipped", reason: "frequency_capped" (with the same frequency_cap_id and retry_after_seconds fields) and the batch moves on. Handle the skip status in your result reconciliation rather than trying to pre-filter caps yourself.

Distinguish this from a delivery failure: the carrier never saw the message, no slot was consumed, and nothing about the recipient’s record needs repair — the send simply has to wait for a slot in the window.

3. Retriable vs terminal

Classify every error you handle into one of three buckets — this decision determines whether you retry, defer, or surface the failure to the caller:

Class	Examples	Retry?	Handling
Validation (4xx, your input is wrong)	`INVALID_PHONE_NUMBER`, `INVALID_FROM_NUMBER`, `VALIDATION_ERROR`, `MISSING_REQUIRED_FIELD`	No — same input, same 422	Correct the payload per `details.field` / `details.expected`, then resend
Throttle / cap (429, wait then retry)	`RATE_LIMITED`, `RATE_LIMIT_EXCEEDED`, `FREQUENCY_CAP_EXCEEDED`, `VERIFY_RECIPIENT_RATE_LIMITED`	Yes — after the server-provided wait	Honor `retry_after` / `retry_after_seconds` / the `Retry-After` header
Transient (5xx, platform-side, safe to retry)	`INTERNAL_ERROR`, `SERVICE_UNAVAILABLE`, `BALANCE_SERVICE_UNAVAILABLE`, `SOFTSWITCH_UNHEALTHY`	Yes — with backoff and a bounded retry count	Exponential backoff, bounded attempts, idempotency key on the original request

The decision tree:

Is error.code in the permanent set you know are yours? (INVALID_PHONE_NUMBER, NO_SENDER_CONFIGURED, INSUFFICIENT_BALANCE, RECIPIENT_OPTED_OUT, …) → Terminal. Fix the input or surface to the caller; never retry the same body.
Is the status 429? → Deferred. Read retry_after / retry_after_seconds and re-queue the send after that delay. FREQUENCY_CAP_EXCEEDED is a per-recipient skip; RATE_LIMITED is a global back-off.
Is the status 5xx? → Retriable. INTERNAL_ERROR and SERVICE_UNAVAILABLE represent platform-side conditions that resolve; retry with exponential backoff and a capped attempt count. If the original request was a send, reuse the same idempotency key so a retry can’t double-send.
Unlisted error.code on a 5xx? Treat it as retriable until the reference says otherwise — the platform returns 5xx only for server-side conditions, and preferring a cautious retry over dropping a recipient is the safe default.

4. From error to remedy via `meta.docs_url`

Every envelope carries meta.docs_url, a per-code link into the Error Code Reference:

"meta": {
  "request_id": "req_abc123",
  "docs_url": "https://docs.orbit.devotel.io/errors/INVALID_PHONE_NUMBER"
}

Use it two ways:

In developer tooling. Log or surface docs_url alongside the error so the person debugging lands directly on the code’s anchor instead of searching the reference.
In your own error dictionary. Map the codes you handle to the remediation you apply (INVALID_PHONE_NUMBER → normalize E.164; FREQUENCY_CAP_EXCEEDED → defer recipient), and point the mapped entry at the same docs anchor for the human follow-up.

The full registry with remediation notes per code is the single source of truth — reach for it before inventing handling for a code you haven’t seen:

Error Code Reference — every registered code, with HTTP status and cause.
Error Codes — the common codes, pinned with the envelope shape.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

API error handling by example

API error handling by example

1. The error envelope

2. Three worked failures with the fix in code

(a) `INVALID_PHONE_NUMBER` — a non-E.164 `to` on an SMS send

(b) `RATE_LIMITED` 429 — read `Retry-After`, back off exponentially

(c) `FREQUENCY_CAP_EXCEEDED` — skip the recipient, don’t fail the batch

3. Retriable vs terminal

4. From error to remedy via `meta.docs_url`

See also

​API error handling by example

​1. The error envelope

​2. Three worked failures with the fix in code

​(a) INVALID_PHONE_NUMBER — a non-E.164 to on an SMS send

​(b) RATE_LIMITED 429 — read Retry-After, back off exponentially

​(c) FREQUENCY_CAP_EXCEEDED — skip the recipient, don’t fail the batch

​3. Retriable vs terminal

​4. From error to remedy via meta.docs_url

​See also

API error handling by example

1. The error envelope

2. Three worked failures with the fix in code

(a) `INVALID_PHONE_NUMBER` — a non-E.164 `to` on an SMS send

(b) `RATE_LIMITED` 429 — read `Retry-After`, back off exponentially

(c) `FREQUENCY_CAP_EXCEEDED` — skip the recipient, don’t fail the batch

3. Retriable vs terminal

4. From error to remedy via `meta.docs_url`

See also