Error Codes

Error response format

There are two error envelope shapes across the API. Most REST v1 endpoints use a flat envelope. The OpenAI-compatible /v1/chat/completions endpoint uses a nested envelope that matches the OpenAI SDK error shape so client libraries parse it natively.

Flat envelope (REST v1)

Used by every endpoint under /api/v1/* except /chat/completions. Body includes a code, a human-readable message, and optionally a details object with field-level info.

// Standard error
HTTP/1.1 401 Unauthorized
{
  "code":    "INVALID_API_KEY",
  "message": "The API key provided is invalid or has been revoked."
}

// Validation error with field details
HTTP/1.1 400 Bad Request
{
  "code":    "VALIDATION_ERROR",
  "message": "Request validation failed.",
  "details": {
    "language": "Must be a valid BCP-47 language code.",
    "max_duration": "Must be between 60 and 7200."
  }
}

Nested envelope (chat completions)

Used by POST /api/v1/chat/completions. Every field is present on every error. Every response also includes an X-Request-Id header that matches error.request_id. Include that value when you contact support.

HTTP/1.1 402 Payment Required
X-Request-Id: chatreq-8a1e6b9f-3c2d-4d5f-9e2b-1a0b2c3d4e5f

{
  "error": {
    "message": "Insufficient credits. Estimated worst-case cost €0.0362 exceeds balance €0.0100.",
    "type": "invalid_request_error",
    "code": "INSUFFICIENT_CREDITS",
    "param": null,
    "request_id": "chatreq-8a1e6b9f-3c2d-4d5f-9e2b-1a0b2c3d4e5f"
  }
}

type is one of invalid_request_error, authentication_error, permission_error, rate_limit_error, upstream_error, server_error. See the full list of chat completions codes on the chat completions page.

Always check the code field programmatically. Never match on the message string, which may change between releases.

HTTP status codes

Authentication errors

Chat completions error codes

These codes are specific to POST /api/v1/chat/completions and use the nested envelope with a type field.

For security reasons the message field on chat-completion errors never echoes fragments of your request. Include request_id when contacting support.

Rate limit headers

These headers are included on every API response so you can monitor your limit consumption before hitting a 429.

// Handle 429 with exponential back-off
async function apiRequest(url, options, attempt = 0) {
  const res = await fetch(url, options);

  if (res.status === 429) {
    const reset = res.headers.get('X-RateLimit-Reset');
    const waitMs = reset
      ? (parseInt(reset) * 1000 - Date.now()) + 100
      : Math.min(1000 * 2 ** attempt, 30000);

    await new Promise(r => setTimeout(r, waitMs));
    return apiRequest(url, options, attempt + 1);
  }

  return res;
}

Call ended_reason values

The ended_reason field on a completed call tells you exactly why the call ended. Available in GET /v1/calls/:callId and in the call.ended webhook payload.

Call status and disposition

Common validation errors

Retrying requests

The following errors are safe to retry. All others should not be retried automatically without fixing the underlying cause first.