> ## Documentation Index
> Fetch the complete documentation index at: https://hellotars.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API errors

> Handle shared problem responses using stable codes, retry guidance and a request ID for support.

Failures use application/problem+json with the same shape across API resources.

## Problem object

| Field | Meaning |
| - | - |
| title | Human-readable summary |
| status | HTTP status code |
| detail | Explanation for this request |
| instance | req\_ request ID for logs and support |
| code | Stable machine-readable code |
| retryable | Whether retrying can succeed |

Some codes add extensions such as required, region, errors, field, contactId, callId or reason.

Validation errors contain entries with path, code and optional message. Branch on code rather than matching title or detail text.

## Codes

| Code | Status | Title | Retryable | Extensions |
| - | - | - | - | - |
| invalid\_json | 400 | Request body is not valid JSON | false | None |
| validation\_failed | 400 | Request failed validation | false | errors |
| variable\_key\_not\_allowed | 400 | A variable is not allowed | false | errors |
| invalid\_variable\_value | 400 | A variable value is not valid | false | errors |
| cursor\_expired | 400 | The cursor has expired | false | None |
| cursor\_mismatch | 400 | The cursor belongs to another request | false | None |
| campaign\_mode\_invalid | 400 | Campaign is not in webhook mode | false | None |
| unauthorized | 401 | Missing or invalid authorization | false | None |
| invalid\_key | 401 | Invalid or revoked API key | false | None |
| session\_invalid | 401 | The voice widget session is invalid | false | None |
| insufficient\_balance | 402 | Insufficient credit balance | false | None |
| organization\_inactive | 403 | Organization is inactive | false | None |
| billing\_locked | 403 | A paid plan is required | false | None |
| permission\_missing | 403 | The API key lacks the permission this endpoint requires | false | required |
| resource\_not\_allowed | 403 | The API key cannot reach this resource | false | None |
| entitlement\_missing | 403 | Voice is unavailable for this organization | false | callId, reason |
| origin\_not\_allowed | 403 | This site may not start calls | false | None |
| recaptcha\_failed | 403 | reCAPTCHA verification failed | false | None |
| consent\_revoked | 403 | Recipient has opted out | false | None |
| us\_marketing\_blocked | 403 | US marketing message blocked | false | None |
| channel\_test\_mode | 403 | Channel is in test mode | false | None |
| quota\_exceeded | 403 | A plan limit has been reached | false | None |
| forbidden | 403 | The request is not allowed | false | None |
| not\_found | 404 | Not found | false | None |
| method\_not\_allowed | 405 | Method not allowed | false | None |
| wrong\_region | 409 | The organization lives in another region | false | region |
| conflict | 409 | The resource changed since you read it | false | None |
| contact\_exists | 409 | A contact with this email or phone already exists | false | field, contactId |
| idempotency\_key\_reuse | 409 | Idempotency key was used for another request | false | None |
| agent\_unavailable | 409 | The agent is not available | false | callId, reason |
| call\_not\_live | 409 | The call is not live | false | None |
| call\_still\_live | 409 | The call is still live | false | None |
| call\_content\_deleted | 409 | The call content has been deleted | false | None |
| invalid\_state | 409 | The resource does not allow this change now | false | callId, reason |
| campaign\_paused | 409 | Campaign is not active | true | None |
| template\_version\_drift | 409 | Template version drift | false | None |
| channel\_unavailable | 409 | Channel account is unavailable | true | None |
| artefact\_deleted | 410 | The artefact has been deleted | false | None |
| campaign\_gone | 410 | Campaign has ended | false | None |
| payload\_too\_large | 413 | Request body is too large | false | None |
| template\_not\_approved | 422 | Template is not approved | false | None |
| channel\_misconfigured | 422 | Channel is misconfigured | false | None |
| channel\_reauth\_required | 422 | WhatsApp connection expired : reconnect the account | false | None |
| meta\_rejected | 422 | Message rejected by WhatsApp | false | None |
| rate\_limited | 429 | Rate limit exceeded | true | callId, reason |
| concurrency\_limit\_reached | 429 | No call slot is free | true | callId, reason |
| worker\_busy | 429 | All agents are busy right now | true | callId, reason |
| meta\_rate\_limited | 429 | WhatsApp is rate limiting sends | true | None |
| internal\_error | 500 | Internal error | false | None |
| upstream\_unavailable | 503 | A provider Tars depends on is unavailable | true | None |
| meta\_unavailable | 503 | WhatsApp is temporarily unavailable | true | None |
| worker\_not\_deployed | 503 | No voice worker serves this deployment | false | callId, reason |
| worker\_unavailable | 503 | No voice worker is available right now | true | callId, reason |

## Retrying

Retry only when retryable is true. Every retryable problem carries Retry-After in seconds. Wait at least that long before trying again.

For call creation, preserve Idempotency-Key when retrying the same request. See [Requests](https://hellotars.com/docs/developer/requests.md).

## Request IDs

Keep instance with your logs. Include it when asking support about a failure. Do not log API keys or secret request headers.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.