Error codes

Every error the API raises itself has the same JSON shape and a stable machine-readable code. Switch on code, not on message: messages are for people and may be reworded.

{ "error": { "code": "idempotency_conflict", "message": "…" } }

• A 429 carries a Retry-After header (seconds).
• Objects that belong to another account return 404 not_found, never 403, so an ID cannot be probed.
• Malformed request bodies (a missing field, a wrong type) are rejected by the framework's own validation with 422 and a detail array instead of the error object.

How this page is generated

This page is generated, not written by hand. uv run python -m scripts.gen_errors_doc parses the API source (services/api/app) without running it: it collects every DomainError subclass in app/core/errors.py and elsewhere with its HTTP status and default code, the MANAGEMENT_ERROR_CODES table, and every call that raises one of those classes with an explicit literal code. The meaning column is the API's own message from one place the code is raised (… marks a value filled in at run time); generic codes get a short description instead.

The table covers every API surface, including the dashboard and platform administration. Merchant integrations using an API key mostly see unauthorized, api_key_expired, forbidden, merchant_suspended, not_found, invalid, conflict, idempotency_conflict, order_conflict, rate_limited, pricing_unavailable and platform_paused.

3 raise sites compute their code at run time (a variable rather than a literal); a static scan cannot name those, so they are not listed separately.

All codes