The error catalog
support backbone · 478 catalog codes · 5 carried here verbatim · Machine form: /v1/diagnostics/error-catalog · Markdown
Every error the API returns carries a stable code, and the catalog gives each code its typical HTTP status, whether retrying can help, and what an agent should do next — so an agent branches on the code instead of parsing prose. The catalog is served whole and per code. The codes a pre-call or registration attempt most often meets are carried in this topic's record, verbatim from the catalog: the two pre-call request errors, the unreachable-server error (the one retryable error among them — the server could not be probed and nothing was registered), and the redirected-URL error (register the destination directly). This diagnostics surface adds one code of its own, for a topic name outside the set.
Entry points
- catalog:
/v1/errors - one_code:
/v1/errors/{code} - diagnostics:
/v1/diagnostics
Checks to run
- GET /v1/errors — the whole catalog: every code with its typical status, retryable flag and action.
- GET /v1/errors/<code> — one code's entry, for the exact error an answer carried.
Outcomes
- retryable: true — The catalog says retrying can help — the failure is a state that can change (a server that could not be probed, a record not yet sealed). Next step: Follow the code's action, then retry the original request; do not change the request's meaning to make the error go away.
- retryable: false — Retrying the same request cannot help: the request itself, or a fact it names, has to change. Next step: Make the change the code's action names — a corrected URL, a registered destination, a field within its stated shape — then send the corrected request.
- diagnostic_not_found (404) — No diagnostic topic exists under that name: the topics are the fixed set listed at GET /v1/diagnostics. Next step: List the topics at GET /v1/diagnostics and read the one that matches the failure in hand.