Errors
CALL-E returns stable error envelopes for Developer API request failures.
Error envelope
Code
SDK methods raise typed SDK errors while preserving the stable API error code and response details.
Stable error codes
invalid_requestunauthorizedforbiddenrate_limit_exceededinsufficient_balanceunsupported_regionunsupported_languagerecipient_blockedpolicy_violationcall_not_readyno_recipientsinvalid_recipientinvalid_phoneresult_schema_invalidrecipient_result_schema_invalididempotency_conflictgoal_not_publishedgoal_not_executablegoal_not_readyschema_override_not_allowedvariables_invalidprovider_unavailableinternal_errornot_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 API call task | Lifecycle status is stable. failure_code is a nullable string without a published enum; failure_message is nullable human-readable context. |
| Goal Runs API | GoalRunError.code is a separate enum that includes no_answer and declined. |
For Calls API 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 Goal Run codes no_answer and declined do not define Calls API
failure_code values. The Calls API currently 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
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.
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 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.
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.
call_not_ready means the call task has not reached a terminal state.
provider_unavailable applies only before durable Goal Run acceptance. After acceptance, dispatch, call, or result-processing failures are reported in the existing Goal Run resource's top-level error field. Retry transport failures only when the workflow can preserve the same idempotency key and request.
internal_error is retryable only when the workflow can safely tolerate retry.