# Errors

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

## Error envelope

```json
{
  "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](/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.