Skip to main content

​
Error Handling

All API errors use a consistent JSON structure and appropriate HTTP status codes.

​
Response format

Errors include a top-level error object and a meta object: 
{
  "error": {
    "code": "validation_error",
    "message": "Invalid request",
    "details": {
      "field": "phone_number",
      "reason": "Must be in E.164 format"
    }
  },
  "meta": {
    "request_id": "uuid",
    "ts": "2026-02-04T12:00:00Z"
  }
}
  • code: Machine-readable error code (e.g. validation_error, not_found, rate_limit_exceeded).
  • message: Human-readable description.
  • details: Optional object with extra context (validation fields, IDs, etc.).
  • meta.request_id: Use this when contacting support.
  • meta.ts: Server timestamp of the response.

​
HTTP status codes

StatusMeaning
400Bad request (malformed body or query)
401Unauthorized (missing or invalid API key / JWT)
403Forbidden (e.g. IP not whitelisted)
404Not found (resource or ID does not exist)
422Validation error (schema or business rule)
429Rate limit exceeded
500Internal server error
502Bad gateway (external provider error, e.g. voice or telephony provider)

​
Common codes

  • validation_error (422): Check details for field-level errors. Business rules (e.g. no outbound number assigned) also return 422.
  • not_found (404): The resource or ID in the path/body does not exist.
  • unauthorized (401): Provide a valid API key in the Authorization: Bearer <key> header.
  • forbidden (403): Key is valid but action or origin is not allowed.
  • provider_error (502): An external provider (e.g. voice or telephony) failed. Check the error message or, for calls, context.last_error on the call record.
  • rate_limit_exceeded (429): Respect Retry-After and rate limit headers.

​
Best practices

  1. Use meta.request_id in support requests and logs.
  2. On 429, back off using Retry-After and avoid tight retry loops.
  3. Do not rely on message text for logic; use error.code and status codes.
For endpoint details and request bodies, see the API Reference.