# Error Handling

> Tchavi returns standard HTTP status codes with a structured JSON error body.

- Canonical: https://tchavi.com/en/docs/errors

---


Tchavi returns standard HTTP status codes. Errors include a JSON body:

```json
{
  "error": {
    "code": "insufficient_credits",
    "message": "You don't have enough credits for this request.",
    "status": 402
  }
}
```

## Common error codes

| Status | Code                     | Description                                           |
| ------ | ------------------------ | ----------------------------------------------------- |
| 401    | invalid_api_key          | Missing or invalid API key                            |
| 402    | insufficient_credits     | Not enough credits — recharge to continue             |
| 403    | model_not_allowed        | Your account tier doesn't include this model          |
| 429    | rate_limit_exceeded      | RPM limit reached — check Retry-After header          |
| 429    | user_rate_limit_exceeded | Per-user RPM limit reached — upgrade plan to increase |
| 429    | tpm_rate_limit_exceeded  | Token-per-minute limit reached — wait before retrying |
| 500    | internal_error           | Server error — retry or contact support               |
| 502    | upstream_error           | AI provider is temporarily unavailable                |

See also [Rate Limits](/en/docs/rate-limits) and [Credits & Billing](/en/docs/credits).