# Errors

> The error codes of the KONG API AI API: status, code, what it means and what to do in each case.

Source: https://kongapiai.com/en/docs/errors

## The shape of an error

Every error is JSON of the same shape:

```json
{"error": {"code": "key_limit", "message": "…"}}
```

Handle errors by `code`. The `message` is for people and may change.

## Error codes

| Status | Code | Meaning and what to do |
| --- | --- | --- |
| 400 | `invalid_json` | The body is not valid JSON. |
| 400 | `model_required` | The `model` field is missing. |
| 400 | `unknown_model` | The model is not in the catalog. See [Models and prices](https://kongapiai.com/en/docs/models). |
| 401 | `unauthorized` | The key is missing or not valid. |
| 402 | `key_limit` | The key reached its monthly limit. Raise the limit or wait for the new month. |
| 402 | `budget_exceeded` | A limit of the member, customer or workspace ran out. |
| 402 | `insufficient_budget` | The available credits cannot hold the most this request could cost. Add credits. |
| 403 | `key_paused`, `key_revoked` | The key is paused or revoked. |
| 403 | `model_forbidden` | The model is outside this key's models. |
| 403 | `application_disabled`, `customer_disabled` | The app or the customer is turned off. |
| 404 | `not_found` | The address is not supported, or the request was not found. |
| 409 | `duplicate_request` | A request with this `Idempotency-Key` was already accepted. Read its state at `/v1/requests/{id}`. |
| 409 | `idempotency_conflict` | The same `Idempotency-Key` with a different body. Use a new ID. |
| 413 | `body_too_large` | The body is over 2 MB. |
| 429 | `own_quota_unavailable` | None of your own sources can serve and credits fallback is off. |
| 429 | `tenant_rate_limit` | Too many requests. Retry after the time in the `Retry-After` header. |
| 503 | `workspace_paused` | An admin paused all keys. |
| 503 | `queue_timeout` | No suitable source within the waiting time. Retry later. |
| 503 | `gateway_overloaded`, `draining` | The system is full or being updated. Retry in a few seconds. |

## Which errors to retry

- **Retry:** `429` and `503`. Wait for `Retry-After` if it is there, and keep the same `Idempotency-Key` so you are not charged twice.
- **Do not retry:** `400`, `401`, `403`, `413`. Fix the request or the key.
- **Needs a person:** `402`. Raise the limit or add credits.

## Are failed requests charged

No. Failed requests are not charged. If the outcome is unknown, the amount stays on hold until it is reconciled, then it is settled or released.
