# Errors

> Every error code with its HTTP status, whether to retry, what it means and how to fix it, and the shape of an error body.

Source: https://docs.b7r.app/errors

Every error has the same shape, an RFC 9457 problem body sent as `application/problem+json`, whatever part of the path refused the call. Build your logic on `code`, which never changes and is never translated. Retry only when `retryable` is `true`.

> The `title` follows `Accept-Language`: Arabic when it starts with `ar`, English otherwise. Show it to people if you like, but never parse it.

| Code | HTTP | Retry | Meaning | Fix |
| --- | --- | --- | --- | --- |
| `unauthorized` | 401 | no | Invalid or missing API key. The key is missing, malformed, unknown, revoked or expired. Every case answers the same way. | Send the whole key as `Authorization: Bearer <key>`. If it still fails, create a new key in the app. |
| `area_forbidden` | 403 | no | This key cannot use this area. The key does not hold the area this endpoint needs; `valid_values` in `errors` names it. The area is checked before any id is looked up, so this answer says nothing about whether the id exists. | Use a key with that area, or create one. See [Keys and access](https://docs.b7r.app/keys-and-access#areas). |
| `account_inactive` | 403 | no | The account is not active. The account that owns the key cannot use B7R right now. | Sign in to b7r.app, or contact B7R support. |
| `connection_disabled` | 403 | no | The Custom API is turned off for this account. B7R has switched the Custom API off for this account only. | Contact B7R support. |
| `not_found` | 404 | no | Not found. The path is not part of the API, or the id does not exist. Another account's id answers `404 not_found` too, exactly like an id that does not exist. | Check the path against the reference and the id against your records. |
| `method_not_allowed` | 405 | no | Method not allowed. The path exists, with another method. | Use the method the reference shows. |
| `invalid_request` | 400 | no | The request is not valid. The query, the body or the form of the request is not accepted. `errors` lists each problem with a `pointer` and, when the choice is short, `valid_values`. A query or body field the endpoint does not know is refused too, with the error code `unknown_field`: it is never ignored. | Fix what `errors` names, then send the corrected request. Sending the same one again fails again. |
| `idempotency_key_required` | 400 | no | The Idempotency-Key header is required. A POST arrived without an `Idempotency-Key` header, or with an empty one. | Send a new key with every POST. See [Safe retries](https://docs.b7r.app/safe-retries). |
| `request_too_large` | 413 | no | The request is too large. The body is over its cap of 262144 bytes. | Send less. See [Limits and retries](https://docs.b7r.app/limits-and-retries#request-size). |
| `unsupported_media_type` | 415 | no | Unsupported content type. A POST body is not sent as `application/json`. | Send JSON with `Content-Type: application/json`. |
| `rate_limited` | 429 | yes | Too many requests, try again shortly. Too many calls in a short time. Nothing changed and nothing was charged. | Wait the seconds in `Retry-After`, then send the same request. |
| `internal_error` | 500 | yes | Something went wrong on our side. Something failed on B7R's side. | Retry with backoff. If it keeps failing, contact B7R support with the `request_id`. |
| `upstream_unavailable` | 502 | yes | A service we depend on is unavailable. A service on the way to B7R did not answer correctly. | Retry with backoff. |
| `api_unavailable` | 503 | yes | The Custom API is not available. The API is switched off for everyone for now. `GET /v1/status` answers `api_enabled: false`. | Retry later; `GET /v1/status` shows when it is back. |
| `request_expired` | 503 | yes | The request expired, send it again. The request reached B7R too late or twice, for example after a delay on the way. | Send it again, with the same `Idempotency-Key` for a POST. |
| `service_unavailable` | 503 | yes | The service is unavailable, try again shortly. B7R is briefly unavailable. | Retry with backoff. |
| `upstream_timeout` | 504 | yes | A service we depend on timed out. No answer came in time. | Retry with backoff, with the same `Idempotency-Key` for a POST. |

## The shape of an error

| Field | Type | What it holds |
| --- | --- | --- |
| `type` | string | This page with the code as anchor, for example `https://docs.b7r.app/errors#invalid_request`. |
| `title` | string | A short message in the caller's language. |
| `status` | integer | The HTTP status, repeated. |
| `code` | string | One code from the table above. |
| `retryable` | boolean | Whether sending the same request later can succeed. |
| `request_id` | string | The same value as the `X-Request-Id` header. |
| `errors` | array | Only when there are details: `code`, `message`, and `pointer` (a JSON Pointer that starts with `/body` or `/query`, such as `/body/zone_ids/0` or `/query/limit`), `line` or `valid_values` when they apply. |

400 problem+json:

```json
{
  "type": "https://docs.b7r.app/errors#invalid_request",
  "title": "The request is not valid",
  "status": 400,
  "code": "invalid_request",
  "retryable": false,
  "request_id": "req_7Hc2aP9xLm4Qw8Rt1Zk5Vb3N",
  "errors": [
    {
      "pointer": "/body/zone_ids/0",
      "code": "unknown_zone",
      "message": "Unknown print zone",
      "valid_values": [
        "5e7a9c1b-3d5f-4b7a-9c1e-2f4a6b8c0d2e",
        "6f8b0d2c-4e6a-4c8b-8d2f-3a5b7c9d1e3f"
      ]
    }
  ]
}
```

## Codes inside errors

Each entry of `errors` has its own `code`. More may be added; treat an unknown one like `invalid_value`.

| Code | Message |
| --- | --- |
| `required` | This field is required |
| `unknown_field` | Unknown field |
| `invalid_type` | The value has the wrong type |
| `invalid_value` | The value is not accepted |
| `too_small` | The value is below the minimum |
| `too_large` | The value is above the maximum |
| `invalid_cursor` | The cursor is not valid for this list |
| `unknown_product` | Unknown product |
| `unknown_technique` | Unknown printing technique |
| `unknown_zone` | Unknown print zone |
| `unknown_carrier` | Unknown carrier |
| `missing_area` | The key does not have this area |
