Error envelope

Every error response — on every surface, from validation failures to authorization rejections to server errors — uses the same JSON shape. Write one error handler and it works against the whole API.

{
  "code": "string",
  "message": "human-readable summary",
  "details": {}
}

• code — a stable, machine-readable identifier you can branch on.
• message — a human-readable summary, safe to log; not intended for end-user display verbatim.
• details — optional structured context (e.g. per-field validation errors). Present when there's more to say.

This envelope is documented in OpenAPI as a shared schema and referenced by every endpoint's 4xx/5xx responses, so it shows up consistently in the API reference.

Common status codes

The canonical code catalog is published with the API reference. Until the generated reference lands, treat code as stable and message as informational.