Copy page

Guides

Errors

CALL-E returns stable error envelopes for Developer API request 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
• input_incomplete
• unauthorized
• forbidden
• rate_limit_exceeded
• account_concurrency_exceeded
• account_concurrency_unavailable
• llm_token_budget_exceeded
• llm_token_budget_unavailable
• 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
• goal_not_published
• goal_not_executable
• goal_not_ready
• schema_override_not_allowed
• variables_invalid
• provider_unavailable
• internal_error
• not_found

Accepted call execution outcomes

The stable APIError.code values above describe an HTTP request failure. They are separate from the outcome of a call task or Goal Run that was accepted and later reached a terminal state.

Surface	Stable contract
Developer API request	APIError.code uses the stable values listed above.
Calls and Goal Runs	Poll while result_status is pending. call_outcome separates ordinary telephone outcomes from technical errors; an unavailable result may have both result and error null.
Legacy call tasks	Lifecycle status is stable. failure_code is a nullable string without a published enum; failure_message is nullable human-readable context.

For legacy call-task resources, treat failure_code and failure_message as diagnostic context. Preserve the raw values for support, but do not branch retry, reporting, or analytics logic on a particular string.

The call outcomes no_answer, busy and declined do not define legacy call-task failure_code values. The legacy API does not guarantee a distinct no-answer or callee-decline value at the call-task, recipient, or attempt level. If the documented Calls fields do not establish that distinction, keep the business outcome unresolved. Do not infer that a recipient declined from a generic failed state or an undocumented failure message, and do not automatically retry based only on an undocumented failure string.

Recovery guidance

Choose the next action

First distinguish an HTTP request failure from an accepted call's result. The Quickstart explains how to retain the original request, key and Call ID for that purpose.

The provider_unavailable Goal Run contract does not establish the cause of an arbitrary Calls API 503. For support, retain the SDK version, UTC timestamp, HTTP status, error code/details, and existing Call ID if available. Redact credentials, phone numbers, and private transcript content before sharing.

Account controls

For POST /v1/calls, account controls can reject creation before planning:

HTTP status and code	Recovery
429 account_concurrency_exceeded	Wait for an active task to finish. Inspect details.line_type and details.max_active_tasks for the effective limit. Shared-line errors can include KYC and number-purchase guidance in details.upgrade; purchased-line errors ask you to wait for capacity.
429 llm_token_budget_exceeded	Wait for the account's LLM quota window to reset before attempting more calls.
503 account_concurrency_unavailable or 503 llm_token_budget_unavailable	The account-control check is unavailable. Back off before retrying; this is not evidence that the limit was exceeded.

Preserve the original request and idempotency key when recovering an uncertain creation. A persisted creation rejection replays its original error; after resolving a confirmed rejection, use a new key for an intentionally new attempt. See Legacy Calls recovery.

Code-specific 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 CALL-E could not resolve a supported calling configuration for the request.

On Call creation these errors return HTTP 422 before durable acceptance. Explicit unsupported targets are rejected before preparation; an inferred locale is checked after inference. details.field identifies region or locale, while details.region and details.locale identify the rejected target. No Call is created, and the rejected request does not reserve the idempotency key. Configuration access failures and conflicting profiles retain HTTP 503.

Check the supported regions and languages for the destination and locale you requested. Correct phone formatting alone does not resolve a coverage error.

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 includes a non-empty phones array.

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 returns HTTP 400 when the Calls result_schema is outside the supported scalar-object profile. For example, "type": ["string", "null"] is unsupported even though it is valid general JSON Schema. Correct the schema before retrying; do not treat this as a provider outage.

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

idempotency_conflict has two recovery paths. When details.reason_code == "creation_in_progress", retry unchanged after backoff. Otherwise, the key belongs to another request or owner; check the original payload and identity. Only an intentional new call should get a new key. See Call retry decisions, including completed calls and omitted target hints. Use error.code and structured details for branching; do not parse the English message.

For a lost Calls API create response or an application restart, follow Recover after a restart or lost response.

not_found means a call, Goal, or Goal Run does not exist or is not visible to the current API key. Owner mismatch and hidden Goals use the same code.

goal_not_published means an active Goal has no published RunSpec. goal_not_executable means the Goal is draft, paused, or retired. Existing Goal Run ids remain readable after a lifecycle change.

goal_not_ready means the exact published RunSpec or provider contract does not currently pass the execution gate.

schema_override_not_allowed means the Goal Run request attempted to supply a task, RunSpec selector, schema, materialization setting, or provider configuration owned by the published Goal.

variables_invalid means the scalar variables do not satisfy the input schema of the RunSpec pinned by the Goal Run.

Check the operation and error details for call_not_ready. On POST /v1/calls, planning can reject a request with this code before execution. For a creation rejection asking for missing task information, follow the correction example. A batch request without an eligible purchased default outbound number also returns 422 call_not_ready; check the batch calling requirements. Do not treat every occurrence of this code as permission to create another call.

provider_unavailable identifies an unavailable dependency, not necessarily the telephone provider. Call creation can return it for preparation, authorization, balance-check or configuration access failures. It does not mean no-answer or busy. For Goal Run creation it applies before durable acceptance; later execution or result-processing failures belong to the accepted Run's error field. Preserve the original key and request when retrying an uncertain create.

internal_error is retryable only when the workflow can safely tolerate retry.