Skip to content

Error catalog

Every failure on the Broker Platform API is an RFC 9457 application/problem+json body. Match on code, never on the HTTP status alone: one status covers several distinct conditions, and only the code tells them apart.

{
  "type": "https://docs.sirix.ai/errors/invalid_cursor",
  "title": "Bad Request",
  "status": 400,
  "code": "invalid_cursor",
  "detail": "cursor is not valid",
  "request_id": "01J0000000000000000000000",
  "errors": []
}
  • code is the stable identifier. It is drawn from a closed registry — the table below is that registry in full — and a code never changes meaning.
  • type is https://docs.sirix.ai/errors/<code>. It identifies the code; it is not a link you need to follow.
  • request_id is echoed on every response as the X-Request-Id header, including successes. Log it, and quote it in any support request — it identifies the exact call.
  • errors[] is populated on validation_failed, one entry per rejected field.

Reading this table

  • Retry — safe means replaying the identical request is the correct response to this failure. never means something has to change first.
  • A 404 is deliberately indistinguishable from "exists, but you cannot see it". Visibility is checked before anything else, so no response ever reveals the existence of a record you have no access to.
  • The registry is versioned as a whole, so it includes codes for operations that are not part of the early-access surface yet. You will only ever be returned a code for an operation you can actually call.

API version: 1.0.0

Code HTTP Title Retry
idempotency_key_required 400 Bad Request never
invalid_cursor 400 Bad Request never
invalid_grant 400 Bad Request never
invalid_request 400 Bad Request never
invalid_scope 400 Bad Request never
unsupported_grant_type 400 Bad Request never
invalid_client 401 Unauthorized never
unauthorized 401 Unauthorized never
forbidden 403 Forbidden never
read_only_credential 403 Forbidden never
not_found 404 Not Found never
idempotency_in_flight 409 Conflict never
invalid_state 409 Conflict never
revision_conflict 412 Precondition Failed never
scope_too_wide 413 Payload Too Large never
sort_not_allowed 422 Unprocessable Entity never
validation_failed 422 Unprocessable Entity never
rate_limited 429 Too Many Requests safe
internal_error 500 Internal Server Error safe
not_implemented 501 Not Implemented never
write_contention 503 Service Unavailable safe