# Errors

The error shape the Mestra API returns, and the codes to react to.

Every error from the [API](https://withmestra.com/docs/api/) is JSON:

```json
{"error": "Turn on the API in Settings first.", "code": "api_off"}
```

`error` is a sentence you can show a person. `code` is there when a program should react to it. Every response, errors included, carries an `X-Request-Id` header: quote it to support and we can find the call. You can send your own `X-Request-Id` (up to 128 letters, digits, `.`, `_` or `-`) to tie our logs to yours.

The codes you'll meet first:

| Code            | Status | Meaning                                                                                                                                        |
| --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `api_off`       | `409`  | An owner has turned the API off, which revokes every key. Make new keys once it's back on.                                                     |
| `wrong_key`     | `403`  | The key's permissions don't cover that. The message says what it needs. See [Authentication](https://withmestra.com/docs/api/authentication/). |
| `invalid_token` | `401`  | The key is missing, unknown, expired or revoked.                                                                                               |
| `rate_limited`  | `429`  | Too many calls with this key this minute. Wait `Retry-After` seconds. See [Rate limits](https://withmestra.com/docs/api/#rate-limits).         |

Each operation in the [API reference](https://withmestra.com/docs/api/#resources) lists the codes it can answer.
