Error Codes

Error response format

Every error response returns a JSON body with a code and a human-readable message. Some errors include a details object with field-level information.

// 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."
  }
}

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

HTTP status codes

Authentication errors

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.