Error Codes

For the full error-code reference — every code in the canonical error-code registry, grouped by domain — see the Error Code Reference page. The table below is a focused subset of the codes developers encounter most during integration.

Common Error Codes

Code	HTTP	Description
`UNAUTHORIZED`	401	Missing or invalid API key / bearer token (401).
`INVALID_API_KEY`	401	The API key isn’t recognized—check you’re using the full dv_sk key (401).
`INSUFFICIENT_PERMISSIONS`	403	Authenticated, but the API key / role lacks the permission for this route (403).
`VALIDATION_ERROR`	varies	The request body or query failed schema validation; `details.issues` lists the offending fields (400 or 422).
`BADREQUEST`	400	The request could not be processed. Check that the body is valid JSON (including escaping quotes inside strings) and that `Content-Type` is `application/json`.
`INVALID_PHONE_NUMBER`	422	A phone field isn’t valid E.164 (422).
`NOT_FOUND`	404	The requested resource doesn’t exist (404).
`RATE_LIMITED`	429	Global HTTP 429 rate limit from the platform-wide request limiter, carrying a `retry_after` value in seconds and a matching `Retry-After` header.
`MESSAGE_SEND_FAILED`	502	The provider rejected the message send (502).
`INSUFFICIENT_BALANCE`	402	The tenant balance is too low to cover this operation—top up first (402).
`INTERNAL_ERROR`	500	Unexpected platform error—retry; include `meta.request_id` if it persists (500).
`SERVICE_UNAVAILABLE`	503	The platform or an upstream dependency is temporarily unavailable (503).

Error Response Format

{
  "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"
  }
}

Worked example — a 422 envelope end to end

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

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid SMS payload",
    "status": 422,
    "details": {
      "issues": [
        { "field": "to", "message": "Must be a valid E.164 phone number" }
      ]
    }
  },
  "meta": {
    "request_id": "req_1234",
    "timestamp": "2026-05-10T12:00:00Z",
    "docs_url": "https://docs.orbit.devotel.io/errors/VALIDATION_ERROR"
  }
}

Handling errors in code

Every endpoint — messages, voice, contacts, agents — returns errors in the error envelope above. It is a platform concern, not tied to one endpoint: a Python client and a Go client see the same code / message / status / meta.request_id as a Node client, and the language SDKs mirror that shape so code always indexes into the table above.

Node.js — retrying 429 with backoff

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

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

// Branch on error.code first — only some failures are retriable.
function classify(error: OrbitApiError) {
  // 429 / 5xx are retriable; 4xx terminal errors (INVALID_PHONE_NUMBER,
  // REAUTH_REQUIRED, ...) must not be re-sent.
  const retriable = error.status >= 500 || error.status === 429
  const retryAfterMs = error.details?.retry_after // seconds
  return { retriable, retryAfterMs: retryAfterMs ? retryAfterMs * 1000 : 0 }
}

for (let attempt = 0; attempt < 3; attempt++) {
  try {
    await orbit.messages.send({ channel: 'sms', to: '+14155552671', body: 'Hi' })
    break
  } catch (error) {
    if (error instanceof OrbitApiError) {
      const { retriable, retryAfterMs } = classify(error)
      // Log the envelope fields up front — request_id goes into the
      // structured log so a support ticket can pinpoint the failure.
      console.error({
        code: error.code,
        status: error.status,
        requestId: error.requestId,
        attempt,
      })
      if (!retriable) throw error
      // Honor Retry-After when the server says so; otherwise
      // exponential backoff.
      await new Promise((resolve) =>
        setTimeout(resolve, retryAfterMs || 2 ** attempt * 1000)
      )
    } else {
      throw error
    }
  }
}

Python

import logging
import os
import time

from orbit_sdk import OrbitClient, OrbitError

logger = logging.getLogger(__name__)

client = OrbitClient(api_key=os.environ["ORBIT_API_KEY"])

for attempt in range(3):
    try:
        client.messages.send_sms(to="+14155552671", body="Hi")
        break
    except OrbitError as e:
        # Capture the envelope fields in the structured log entry now —
        # request_id is the key support uses to trace the request.
        logger.error(
            "orbit.send_sms failed",
            extra={
                "code": e.code,
                "status": e.status,
                "request_id": e.request_id,
                "attempt": attempt,
            },
        )
        # 429 / 5xx are retriable; 4xx terminal errors (e.g.
        # INVALID_PHONE_NUMBER) must not be re-sent.
        retriable = e.status is not None and (e.status >= 500 or e.status == 429)
        if not retriable:
            raise
        # Honor the SDK's parsed retry_after (seconds) when present;
        # otherwise exponential backoff.
        retry_after = getattr(e, "retry_after", None)
        time.sleep(retry_after if retry_after is not None else 2 ** attempt)

The Python SDK subclasses OrbitError per HTTP class — OrbitAuthenticationError (401/403), OrbitRateLimitError (429, carries retry_after), OrbitClientError (other 4xx), and OrbitServerError (5xx) — so catch a subclass when you want the specific class. OrbitError itself catches every API failure.

Go

import (
  "errors"
  "log"

  "github.com/devotel/orbit-go/orbit"
)

client, _ := orbit.NewClient(os.Getenv("ORBIT_API_KEY"))
for attempt := 0; attempt < 3; attempt++ {
  _, err := client.Messages().SendSMS(ctx, orbit.SendSMSInput{
    To: "+14155552671", Body: "Hi",
  })
  var apiErr *orbit.Error
  if !errors.As(err, &apiErr) {
    break
  }
  // Log the envelope fields before deciding — RequestID is the key
  // support uses to trace the request.
  log.Printf("kind=%s code=%s status=%d request=%s attempt=%d",
    apiErr.Kind, apiErr.Code, apiErr.StatusCode,
    apiErr.RequestID, attempt)
  // KindServer / KindRateLimit are retriable; KindClient /
  // KindAuthentication are terminal.
  retriable := apiErr.Kind == orbit.KindServer ||
    apiErr.Kind == orbit.KindRateLimit
  if !retriable {
    break
  }
  // Honor the server-supplied RetryAfter when present; otherwise
  // exponential backoff.
  if apiErr.RetryAfter > 0 {
    time.Sleep(apiErr.RetryAfter)
  } else {
    time.Sleep(time.Duration(1<<attempt) * time.Second)
  }
}

Java, C#, PHP, Ruby

The Java, C#, PHP, and Ruby SDKs are pre-publish — not yet on Maven Central, NuGet, Packagist, or RubyGems, so the registry blocks on the per-language SDK pages describe the future registry shape. Vendor the source from the monorepo (sdk-java, sdk-csharp, sdk-php, sdk-ruby) and use the SDK anyway: its escape-hatch client call — client.request (Java and Ruby), client.RequestAsync (C#), or $client->request (PHP) — covers the whole API surface, errors included. Each language page walks the same model end to end. An Orbit-originated OrbitError carries error_code / status_code / request_id; the escape hatch throws the same typed error subclasses as the typed methods, so the catch taxonomy matches every other sample on this page.

client.request("POST", "/messages",
    null,
    Map.of("channel", "sms", "to", "+14155552671", "body", "Hi"),
    null);

await client.RequestAsync("POST", "/messages",
    body: new { channel = "sms", to = "+14155552671", body = "Hi" });

$client->request('POST', '/messages', null, [
    'channel' => 'sms',
    'to' => '+14155552671',
    'body' => 'Hi',
]);

client.request("POST", "/messages",
    body: { channel: "sms", to: "+14155552671", body: "Hi" })

Always include the request_id from the error response meta when contacting Orbit support. This allows us to trace the exact request through our infrastructure.

For the complete list of error codes — including messaging, voice, AI-agent, billing, compliance, and system errors — see the Error Code Reference.

API Reference

All Endpoints

Error Codes

Error Codes

Common Error Codes

Error Response Format

Worked example — a 422 envelope end to end

Handling errors in code

Node.js — retrying 429 with backoff

Python

Go

Java, C#, PHP, Ruby

​Error Codes

​Common Error Codes

​Error Response Format

​Worked example — a 422 envelope end to end

​Handling errors in code

​Node.js — retrying 429 with backoff

​Python

​Go

​Java, C#, PHP, Ruby

Error Codes

Common Error Codes

Error Response Format

Worked example — a 422 envelope end to end

Handling errors in code

Node.js — retrying 429 with backoff

Python

Go

Java, C#, PHP, Ruby