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 | 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
{
"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"
}
}
For the complete list of error codes — including messaging, voice,
AI-agent, billing, compliance, and system errors — see the
Error Code Reference.