# Errors

One error shape for the Texa API, what each status means, and which ones to retry.


Every error from the Texa API has the same shape, and the request's id is in the `X-Request-Id`
header. Quote it to Texa support and we can find the request at once.

```json
{"error": {"type": "invalid_request_error", "code": "invalid",
           "message": "a message has text", "field": "text"}}
```

| Field | Meaning |
|---|---|
| `type` | the family of error, below |
| `code` | a stable machine-readable reason, such as `invalid`, `not_found`, `conversation_closed`, `rate_limited`, `insufficient_credits` |
| `message` | a sentence for a developer. Don't show it to customers |
| `field` | for a request that isn't valid, the part that's wrong |

## Statuses

| Status | Meaning | Retry? |
|---|---|---|
| 400, 422 | The request is not valid. `field` names the part | No: fix the request |
| 401 | The key is missing, unknown or revoked | No |
| 402 | Your prepaid credits are used up. Top up in Texa Desk under **Texa AI → Credits and billing** | After topping up |
| 403 | The key can't do this: a sandbox route with a live key, a suspended account | No |
| 404 | No such route, or nothing with that id in your account | No |
| 409 | The conversation's state doesn't allow it (closed, or with a person), or an `Idempotency-Key` was reused with a different body | No: read `code` |
| 429 | Too many requests. Wait `Retry-After` seconds | Yes, after the wait |
| 500, 502, 503 | Our side | Yes, with the same `Idempotency-Key` or `message_id` |

## Codes worth handling

| `code` | When | What to do |
|---|---|---|
| `conversation_closed` | You sent a message to a closed conversation | Open a new conversation for the customer and send it there ([example](/guides/whatsapp-bot)) |
| `rate_limited` | Over your requests per minute | Wait `Retry-After` seconds |
| `idempotency_key_reused` | The same `Idempotency-Key` with a different body | Use a new key for a new request |
| `idempotency_in_progress` | A retry arrived while the first request with that key is still running | Wait a moment and retry |
| `invalid_api_key` | The key is missing, unknown or revoked | Check the key, or make a new one |
| `insufficient_credits` | The prepaid balance is used up | Top up in Texa Desk |
| `test_key_required` | A sandbox route (fixtures) with a live key | Use a `texa_test_…` key |
| `account_suspended` | The account is suspended | Talk to Texa support |
| `too_large` | An upload over the size limit | Send a smaller file |
| `not_found` | Nothing with that id in this account and environment | Check you're using the right key: sandbox and live don't share conversations |

New codes may be added. Treat an unknown code by its status.

## Texa Desk API errors

The Texa Desk API answers in its own shape: `{"error": "..."}` or `{"message": "...", "errors": [...]}`,
with `401` for a missing or wrong `api_access_token`, `404` for something outside the person's
account or view, and `422` for a refused change, with a sentence you can show as it is.

## Failures Texa AI meets

An error in *your* systems (an action that fails or times out) is not an API error. Texa AI tells
the customer honestly that it couldn't check and offers a person, and the action's result is in the
events. See [actions](/guides/actions).