B7RDevelopers
Get startedErrors
Get started / Errors

Errors

View .md

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
CodeHTTPRetryMeaningFix
unauthorized401NoInvalid 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_forbidden403NoThis 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_inactive403NoThe 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_disabled403NoThe Custom API is turned off for this account. B7R has switched the Custom API off for this account only.Contact B7R support.
not_found404NoNot 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_allowed405NoMethod not allowed. The path exists, with another method.Use the method the reference shows.
invalid_request400NoThe 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_required400NoThe 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_large413NoThe request is too large. The body is over its cap of 262144 bytes.Send less. See Limits and retries.
unsupported_media_type415NoUnsupported content type. A POST body is not sent as application/json.Send JSON with Content-Type: application/json.
rate_limited429YesToo 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_error500YesSomething 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_unavailable502YesA service we depend on is unavailable. A service on the way to B7R did not answer correctly.Retry with backoff.
api_unavailable503YesThe 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_expired503YesThe 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_unavailable503YesThe service is unavailable, try again shortly. B7R is briefly unavailable.Retry with backoff.
upstream_timeout504YesA 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

FieldTypeWhat it holds
typestringThis page with the code as anchor, for example https://docs.b7r.app/errors#invalid_request.
titlestringA short message in the caller's language.
statusintegerThe HTTP status, repeated.
codestringOne code from the table above.
retryablebooleanWhether sending the same request later can succeed.
request_idstringThe same value as the X-Request-Id header.
errorsarrayOnly 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.

CodeMessage
requiredThis field is required
unknown_fieldUnknown field
invalid_typeThe value has the wrong type
invalid_valueThe value is not accepted
too_smallThe value is below the minimum
too_largeThe value is above the maximum
invalid_cursorThe cursor is not valid for this list
unknown_productUnknown product
unknown_techniqueUnknown printing technique
unknown_zoneUnknown print zone
unknown_carrierUnknown carrier
missing_areaThe key does not have this area

Titles and headings of every page. llms-full.txt holds the full text.