# Errors

> Error shape, codes, and how to handle 402.

Errors are JSON with a stable shape — HTTP status says how to react, `code` says what happened:

```json
{
  "error": {
    "message": "This call costs 10 credits and your balance is 4. Top up at https://eroq.ai/dashboard/billing.",
    "type": "insufficient_credits",
    "code": "insufficient_credits"
  }
}
```

| Status | Type | React by |
| --- | --- | --- |
| 400 | invalid_request_error | Fixing the request — the message names the field. |
| 401 | authentication_error | Checking the key; revoked keys 401 immediately. |
| 402 | insufficient_credits | Topping up; nothing was charged. Surface to your own billing. |
| 429 | rate_limit_error | Waiting `Retry-After` seconds, then retrying. |
| 502 | upstream_error | Retrying — the call was refunded automatically. |

402 is a product event, not a bug: catch it and route the user to your top-up flow.

---
Canonical: https://eroq.ai/docs/errors · Index for agents: https://eroq.ai/llms.txt · OpenAPI: https://eroq.ai/openapi.json