Get started / Errors
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.
17 codes
| 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. |
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. |
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. |
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
{
"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 |
