Error Codes

Quick reference of common Devotel API error codes

Error Codes

For the full error code reference with resolution guidance, see the Error Code Reference page.

Common Error Codes

Code	HTTP Status	Description
UNAUTHORIZED	401	Missing or invalid authentication
INVALID_API_KEY	401	API key is malformed, revoked, or does not exist
INSUFFICIENT_PERMISSIONS	403	Authenticated identity lacks the required RBAC role
VALIDATION_ERROR	400 / 422	One or more request fields failed validation
INVALID_PHONE_NUMBER	422	Phone number not in valid E.164 format
NOT_FOUND	404	Resource does not exist
RATE_LIMIT_EXCEEDED	429	Too many requests in the current window
MESSAGE_SEND_FAILED	500	Downstream provider rejected the message
INTERNAL_ERROR	500	Unexpected server error

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. [phone]" }
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-03-08T00:00:00Z",
    "docs_url": "https://orbit-docs.devotel.io/errors/INVALID_PHONE_NUMBER"
  }
}

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