Copy page

Guides

Errors

CALL-E returns stable error envelopes for call task API failures.

Error envelope

Code
{
  "error": {
    "code": "invalid_request",
    "message": "The request body is invalid.",
    "details": {}
  }
}

SDK methods raise typed SDK errors while preserving the stable API error code and response details.

Stable error codes

• invalid_request
• unauthorized
• forbidden
• rate_limit_exceeded
• insufficient_balance
• unsupported_region
• unsupported_language
• recipient_blocked
• policy_violation
• call_not_ready
• no_recipients
• invalid_recipient
• invalid_phone
• result_schema_invalid
• recipient_result_schema_invalid
• idempotency_conflict
• provider_unavailable
• internal_error
• not_found

Recovery guidance

unauthorized means the API key is missing or invalid. Check the Authorization: Bearer header.

forbidden means the key is valid but not allowed to use this resource or capability.

See Authentication for API key setup, server-only usage, and environment separation.

rate_limit_exceeded means the caller should retry after backoff.

insufficient_balance means the project cannot start more calls until billing is resolved.

unsupported_region or unsupported_language means the request asks for a region or locale that CALL-E does not currently support.

no_recipients means CALL-E could not infer any recipients from the task and no explicit recipients were provided.

invalid_recipient means a recipient entry is malformed. Check that each explicit recipient uses supported fields such as phones, region, and locale.

invalid_phone means a phone number is not valid E.164 format. Replace placeholders such as <E164_PHONE> with a phone number you own or are authorized to call.

result_schema_invalid means the whole call task result_schema is not a valid supported JSON Schema object.

recipient_result_schema_invalid means the per-recipient recipient_result_schema is not a valid supported JSON Schema object.

idempotency_conflict means the same idempotency key was reused with a different request body. Reuse keys only for the same external workflow operation.

call_not_ready means the call task has not reached a terminal state.

provider_unavailable and internal_error are retryable only when the workflow can safely tolerate retry.

not_found means the call task id does not exist or is not visible to the current API key.