# Errors

> Every error has the same shape.

Source: https://docs.onari.xyz/docs/api/errors

```json
{
  "error": {
    "code": "unknown_event_type",
    "message": "\"order.placd\" isn't in your events list. Add it in Developers → Events, or check the spelling.",
    "did_you_mean": "order.placed"
  }
}
```

`code` is stable and safe to branch on; `message` is written for people and may change. Some errors add details (`issues`, `did_you_mean`, `index`, `processed`).

| Status | Code | What to do |
|---|---|---|
| 400 | `invalid_request` | Fix the request; `issues` lists the problems. |
| 401 | `invalid_api_key` | Check the key and environment. |
| 402 | `player_limit_reached` | Free plan's monthly player cap. Upgrade, or wait for the 1st. |
| 404 | `player_not_found` | The player hasn't sent an event yet. |
| 404 | `not_found` | Wrong path. |
| 422 | `unknown_event_type` | Add the event in **Developers → Events** or fix the spelling. |
| 429 | `rate_limited` | Wait `Retry-After` seconds, or batch events. |
| 500 | `server_error` | Retry with the same `idempotency_key`; it's safe. |

Retry `429` and `5xx` with backoff. Don't retry `4xx` errors without changing the request.