Error-handling runbook

The error-code reference lists every code the platform can emit. This guide turns that list into an operating procedure: classify the code, decide whether to retry with the same Idempotency-Key or fix the request, and know where the error surfaces when the HTTP response was 200. Run the one-step check under each dominant code before you change code, and use the decision table at the end as your triage shortcut.

1. The error envelope

Every Orbit API error returns the same envelope:

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

error.code is the decision key — branch on it; never parse error.message in code.
error.status gives the coarse HTTP class.
error.details carries the structured context that names the fix — which field failed, how many seconds to wait, which domain rule fired.
meta.request_id is the server-side correlation id — include it when you escalate.
meta.docs_url resolves to the code’s anchor on the reference page.

For a fuller field walk, see API error handling by example.

2. Taxonomy by HTTP class

Class	Examples	Policy
400 / 422	`VALIDATION_ERROR`, `INVALID_PHONE_NUMBER`	Terminal until you fix the request body. Do not retry as-is.
401 / 403	`UNAUTHORIZED`, `INSUFFICIENT_SCOPE`, `INSUFFICIENT_PERMISSIONS`	Terminal for this key. Rotate the key or add the missing scope, then retry.
402	`INSUFFICIENT_BALANCE`	Terminal for this wallet state. Top up, then retry with the same Idempotency-Key.
404	`NOT_FOUND`	Usually terminal. On a resource you just created, one retry is reasonable.
429	`RATE_LIMITED`, `WHATSAPP_RATE_LIMITED`, `VERIFY_RECIPIENT_RATE_LIMITED`	Retryable with backoff. Honor the `Retry-After` header or `details.retry_after_seconds`.
5xx	`INTERNAL_ERROR`, `SERVICE_UNAVAILABLE`	Retryable with exponential backoff and jitter. Use the same Idempotency-Key so a retry that races the original cannot double-create.
502	`MESSAGE_SEND_FAILED`, `EMAIL_SEND_FAILED`	Provider rejected at dispatch — retryable only after the provider check below; otherwise escalate.

Async gates such as QUIET_HOURS_BLOCKED look 4xx-shaped but behave like a clock-based 429: schedule the send inside allowed hours instead of failing the job.

3. Dominant codes and their remediation

`VALIDATION_ERROR` — fix the body, keep the key

The request body or query failed schema validation; the reply is 400 or 422 and details.issues lists each offending field (see section 4). Map the issues back to your form, fix the input, and retry with the same Idempotency-Key — replaying a key after fixing the body is exactly what the replay cache is for.

# check: re-send with the field corrected and the same Idempotency-Key — expect 200/201, not a duplicate
curl -X POST https://api.orbit.devotel.io/api/v1/messages \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Idempotency-Key: order-conf-98421" \
  -H "Content-Type: application/json" \
  -d '{"to":"+14155552671","body":"hi"}'

`INSUFFICIENT_SCOPE` — rotate the key, don’t toggle the endpoint

The API key authenticates but the token lacks the scope this endpoint needs (for example messages:write on sends). Treat 403 as a key/scope problem, not an endpoint outage: issue a new key with the needed scope in the dashboard (Developers → API keys), or have an admin add the scope, then retry. Keep subaccount key scopes minimal.

# check: GET /api/v1/me with the same key returns the scopes it actually carries
curl https://api.orbit.devotel.io/api/v1/me \
  -H "X-API-Key: dv_live_sk_..."

`RATE_LIMITED` — back off, don’t hammer

The tenant’s sliding-window limiter trips at 429. Read the Retry-After header (or details.retry_after_seconds on cap-style limits such as SMS_RATE_LIMITED) and send again once it expires. In the SDK the error is an OrbitRateLimitError, so branch on the class instead of matching the code string.

# check: the response tells you how long to wait — honor it
curl -i -X POST https://api.orbit.devotel.io/api/v1/messages \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Idempotency-Key: throttle-probe-1" \
  -d '{"to":"+14155552671"}' | grep -i retry-after

`INSUFFICIENT_BALANCE` — top up, then replay safely

The wallet pre-flight rejects with 402 before anything dispatches. Top up (or enable auto-top-up) and retry with the same Idempotency-Key: a 402 never dispatched, so reusing the key is safe. Balance mutations additionally guard themselves with DEDUCT_IN_FLIGHT so a retry cannot double-charge.

# check: read the wallet balance before you retry
curl https://api.orbit.devotel.io/api/v1/billing/balance \
  -H "X-API-Key: dv_live_sk_..."

`MESSAGE_SEND_FAILED` — check the provider, not the payload

The send reached a provider and the provider rejected it (502). That is different from VALIDATION_ERROR: the payload was fine, so check the channel — sender registration, template status, channel health — then retry. If the channel dry-run is unhealthy, fix the channel before sending more traffic; if it is healthy, retry with backoff.

# check: re-pull the failing message record and read its provider reason before retrying
curl https://api.orbit.devotel.io/api/v1/messages/msg_abc123 \
  -H "X-API-Key: dv_live_sk_..."

`QUIET_HOURS_BLOCKED` — schedule, don’t retry in place

The universal quiet-hours gate blocks non-voice outbound sends (SMS, MMS, WhatsApp, RCS, Email, Telegram, Viber, Instagram, Messenger, LINE, Apple Messages) during the recipient’s local restricted window. Treat it as a scheduling signal: queue the send for the allowed window rather than retrying immediately. The companion QUIET_HOURS_TIMEZONE_UNKNOWN means the recipient’s timezone could not be resolved — set an explicit timezone on the contact, or schedule into UTC-safe hours.

# check: read the tenant compliance profile to see the active quiet-hours window
curl https://api.orbit.devotel.io/api/v1/compliance/profile \
  -H "X-API-Key: dv_live_sk_..."

Suppression gates — respect the opt-out, route to re-permission

Suppression hits are consent outcomes, not send failures. When a contact sits on the suppression list (opted out, blocked, or bounced), fix it at the contact level — re-permission them through an opt-in flow, or remove the address from your audience — rather than retrying the send. Honoring suppression is a deliverability requirement, not just an error-handling rule.

# check: query the contact's suppression status before attempting a resend
curl https://api.orbit.devotel.io/api/v1/contacts/con_abc123/suppression \
  -H "X-API-Key: dv_live_sk_..."

4. Walking the per-field issues list

VALIDATION_ERROR replies carry details.issues, a per-field array from the server-side schema check. Walk it and map each entry back to your form validation instead of showing the raw message:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "status": 422,
    "details": {
      "issues": [
        { "field": "to",   "message": "Invalid E.164 phone number" },
        { "field": "body", "message": "Required" }
      ]
    }
  }
}

for (const issue of error.details?.issues ?? []) {
  form.setError(issue.field, issue.message);
}

Each entry has a field you map to a form input and a message you can show to the operator. Preserve the server’s field names — don’t re-derive them from the request payload.

5. Errors that surface after a 200

The envelope above describes synchronous rejections. Async surfaces — batch jobs, drip steps, and porting orders — accept the request and report failure later:

Batch jobs and drip steps — the create call returns 200/202; per-item failures land on the job status resource and on webhook events. Consume them with a webhook consumer and read the item-level failure there instead of polling the request log.
Porting orders — a carrier-side rejection arrives after acceptance; poll the order (or consume its webhook) until status flips to rejected and read the rejection object on the order payload for the carrier’s reason.
The message ledger — a 200 on the send endpoint means accepted; delivery failure shows up when you GET the message record as a failed status with a provider rejectReason.

The rule: once the request is accepted, move your error-handling to the lifecycle surface (webhook or status poll), not the HTTP response.

6. Idempotent retry after errors

The idempotency contract tells you when replaying a key is safe. Pair it with the code classification:

Code	Retry with same key?	Backoff first?	Escalate when…
`VALIDATION_ERROR`	Yes, after fixing the body	No	The same field keeps failing
`INSUFFICIENT_SCOPE`	No — rotate the key first	No	Every key with the scope fails
`INSUFFICIENT_BALANCE`	Yes, after topping up	No	The wallet stays under-funded
`RATE_LIMITED` / 429	Yes	Yes — honor `Retry-After`	Backoff exhausts
5xx	Yes	Yes — exponential + jitter	It persists across windows
`MESSAGE_SEND_FAILED`	Only after the provider check	Yes	The channel dry-run is unhealthy
`QUIET_HOURS_BLOCKED`	Reschedule, don’t retry	N/A	Compliance must review
Suppression gates	No — fix the contact consent	No	Suppression trips on new contacts
409 idempotency conflict	No — the body differed	No	Always treat as a client bug

Terminal codes (403 scope, 402 balance, 409 conflict, suppression/consent gates) are terminal for this request shape — you fix a precondition, then retry. Retryable codes (429, 5xx, provider-rejected dispatch) are safe to retry with the same Idempotency-Key because the platform deduplicates on it.

7. Reading errors in the SDK and raw REST

The Node SDK throws an OrbitApiError hierarchy; the subclass is chosen by HTTP class, and .code holds the stable decision key:

import { Devotel, OrbitApiError } from '@devotel-orbit/node';

const orbit = new Devotel({ apiKey: process.env.ORBIT_API_KEY });

try {
  await orbit.messages.send({ channel: 'sms', to: '+14155552671', body: 'hi' });
} catch (error) {
  if (error instanceof OrbitApiError) {
    console.error(error.code, error.status, error.requestId, error.details);
    if (error.isRateLimited) {
      // back off using the Retry-After hint
    } else if (error.code === 'INSUFFICIENT_BALANCE') {
      // top up, then retry with the same Idempotency-Key
    }
  }
  throw error;
}

Subclass accessors (isRateLimited, isClientError, isServerError, status) let you branch without matching code strings; requestId and docsUrl travel into every log line. Over raw REST, read error.code from the JSON envelope the same way. Log the correlation id on either path — it is what support needs to find the server-side trace.

8. The generated reference is a floor

The reference at Error codes enumerates the SDK-typed union of codes — the codes a compile-time client can plan for. At runtime, treat the error.code in the response body as authoritative: new codes land between deployments before the typed union refreshes, and operational codes from channel providers can surface through the envelope without being in the generated table. Branch on the body, and use the reference plus the troubleshooting hub as the lookup layer, not the ground truth.

Decision table

Code	Retry?	Backoff?	Escalate?
`VALIDATION_ERROR`	After body fix	No	Same field keeps failing
`INSUFFICIENT_SCOPE`	After scope added	No	All scoped keys fail
`INSUFFICIENT_BALANCE`	After top-up	No	Wallet still low
`RATE_LIMITED` / 429	Yes	Yes (`Retry-After`)	Backoff exhausts
5xx	Yes	Yes (exponential + jitter)	Persists
`MESSAGE_SEND_FAILED`	After channel check	Yes	Channel unhealthy
`QUIET_HOURS_BLOCKED`	Reschedule	N/A	Compliance review
Suppression gates	No	No	Recurring on new contacts
409 idempotency conflict	No	No	Client bug

Cross-links: Error codes reference, API error handling by example, Idempotency and safe retries, Consuming webhooks, Troubleshooting hub.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Error-handling runbook

Error-handling runbook

1. The error envelope

2. Taxonomy by HTTP class

3. Dominant codes and their remediation

`VALIDATION_ERROR` — fix the body, keep the key

`INSUFFICIENT_SCOPE` — rotate the key, don’t toggle the endpoint

`RATE_LIMITED` — back off, don’t hammer

`INSUFFICIENT_BALANCE` — top up, then replay safely

`MESSAGE_SEND_FAILED` — check the provider, not the payload

`QUIET_HOURS_BLOCKED` — schedule, don’t retry in place

Suppression gates — respect the opt-out, route to re-permission

4. Walking the per-field issues list

5. Errors that surface after a 200

6. Idempotent retry after errors

7. Reading errors in the SDK and raw REST

8. The generated reference is a floor

Decision table

​Error-handling runbook

​1. The error envelope

​2. Taxonomy by HTTP class

​3. Dominant codes and their remediation

​VALIDATION_ERROR — fix the body, keep the key

​INSUFFICIENT_SCOPE — rotate the key, don’t toggle the endpoint

​RATE_LIMITED — back off, don’t hammer

​INSUFFICIENT_BALANCE — top up, then replay safely

​MESSAGE_SEND_FAILED — check the provider, not the payload

​QUIET_HOURS_BLOCKED — schedule, don’t retry in place

​Suppression gates — respect the opt-out, route to re-permission

​4. Walking the per-field issues list

​5. Errors that surface after a 200

​6. Idempotent retry after errors

​7. Reading errors in the SDK and raw REST

​8. The generated reference is a floor

​Decision table

Error-handling runbook

1. The error envelope

2. Taxonomy by HTTP class

3. Dominant codes and their remediation

`VALIDATION_ERROR` — fix the body, keep the key

`INSUFFICIENT_SCOPE` — rotate the key, don’t toggle the endpoint

`RATE_LIMITED` — back off, don’t hammer

`INSUFFICIENT_BALANCE` — top up, then replay safely

`MESSAGE_SEND_FAILED` — check the provider, not the payload

`QUIET_HOURS_BLOCKED` — schedule, don’t retry in place

Suppression gates — respect the opt-out, route to re-permission

4. Walking the per-field issues list

5. Errors that surface after a 200

6. Idempotent retry after errors

7. Reading errors in the SDK and raw REST

8. The generated reference is a floor

Decision table