​

Error Handling

​

Response format

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

​

Common codes

• validation_error (422): Check details for field-level errors. Business rules (e.g. no outbound number assigned) also return 422.
• payment_required (402): Billing or usage limit. The API returns 402 when the organization has no active trial or paid plan, the trial has ended, the subscription is inactive, or there are insufficient credits for the operation (e.g. voice clone, widget, knowledge base). Use error.details for context:
  • reason: One of trial_not_started, trial_expired, subscription_inactive, or insufficient_credits.
  • redirect_url: Optional URL to send the user (e.g. /onboarding/trial to start a trial, /settings/billing to update payment).
  • balance / required: For insufficient_credits, optional numeric fields indicating current balance and required amount.
  • Handle 402 by prompting the user to start a trial, subscribe, or upgrade, or by redirecting to the provided URL.
• 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.