Errors and retries

Every error has a stable machine code, a human message, optional field errors and a request id.

Structured error shape

Branch on code, never on the translated message. Show the message to the person and keep requestId in support diagnostics.

json

{
  "code": "entitlement_limit_exceeded",
  "message": "The user band ceiling has been reached.",
  "details": { "used": 50, "ceiling": 50, "band": "C" },
  "requestId": "req_01J..."
}

Retry only safe failures

Retry 429 and transient 5xx responses with bounded exponential backoff and jitter. Respect Retry-After. Do not retry a validation or entitlement error unchanged.

400/422: correct the request
401/403: refresh authority or request access
409: resolve the current state
429/5xx: bounded retry

Commercial errors are conversion surfaces

entitlement_limit_exceeded includes the live count, ceiling, current band and next price. write_blocked explains grace mode. band_below_live_usage states exactly how many records must leave the billable count before a downgrade.