> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes

> Quick reference of common Orbit API error codes

# Error Codes

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

## Common Error Codes

| Code                       | HTTP   | Description                                                                                                                                       |
| -------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `UNAUTHORIZED`             | varies | Platform-defined error code. See source comment in `packages/shared/src/errors.ts` for context.                                                   |
| `INVALID_API_KEY`          | varies | Platform-defined error code. See source comment in `packages/shared/src/errors.ts` for context.                                                   |
| `INSUFFICIENT_PERMISSIONS` | varies | Platform-defined error code. See source comment in `packages/shared/src/errors.ts` for context.                                                   |
| `VALIDATION_ERROR`         | varies | Platform-defined error code. See source comment in `packages/shared/src/errors.ts` for context.                                                   |
| `INVALID_PHONE_NUMBER`     | varies | Platform-defined error code. See source comment in `packages/shared/src/errors.ts` for context.                                                   |
| `NOT_FOUND`                | varies | Platform-defined error code. See source comment in `packages/shared/src/errors.ts` for context.                                                   |
| `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`      | varies | Platform-defined error code. See source comment in `packages/shared/src/errors.ts` for context.                                                   |
| `INSUFFICIENT_BALANCE`     | varies | Platform-defined error code. See source comment in `packages/shared/src/errors.ts` for context.                                                   |
| `INTERNAL_ERROR`           | varies | Platform-defined error code. See source comment in `packages/shared/src/errors.ts` for context.                                                   |
| `SERVICE_UNAVAILABLE`      | varies | Platform-defined error code. See source comment in `packages/shared/src/errors.ts` for context.                                                   |

## Error Response Format

```json theme={null}
{
  "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"
  }
}
```

<Tip>
  For the complete list of error codes — including messaging, voice,
  AI-agent, billing, compliance, and system errors — see the
  **[Error Code Reference](/reference/error-codes)**.
</Tip>