Errors

Every non-2xx response uses one JSON shape:

{
  "error": {
    "code": "not_found",
    "type": "not_found",
    "message": "Organization not found",
    "details": {}
  }
}

type — a coarse category from a fixed set. It determines the HTTP status, so it's the safe field to switch on.
code — a more specific, stable machine string. Never reworded once shipped, but open-ended: treat an unrecognized code by falling back to its type (or the HTTP status).
message — human-readable, may change between releases. Don't parse it.
details — optional structured context carried by a few codes (e.g. setup steps for database_not_initialized). Absent otherwise.

The HTTP status is authoritative and always agrees with type.

Error types

`type`	HTTP	Meaning
`validation`	400	The request was malformed or failed a field/shape check.
`unauthorized`	401	Missing or invalid credentials.
`forbidden`	403	Authenticated, but not allowed.
`insufficient_scope`	403	The token is valid but lacks the required scope.
`not_found`	404	No matching resource.
`conflict`	409	The request conflicts with existing state (e.g. a duplicate).
`rate_limited`	429	Too many requests — retry after a short wait.
`upstream`	502	A dependency the API called failed.
`unavailable`	503	The endpoint is temporarily unavailable.
`internal`	500	An unexpected server error.

Common codes

code is more specific than type. The ones you'll see most often:

`code`	`type`	When
`validation_failed`	`validation`	A request body failed schema validation.
`bad_request`	`validation`	A business rule rejected the request.
`invalid_json`	`validation`	The body wasn't valid JSON.
`payload_too_large`	`validation`	The request body exceeded the size cap.
`unauthorized`	`unauthorized`	Sign-in or a valid token is required.
`forbidden`	`forbidden`	The caller isn't permitted to do this.
`insufficient_scope`	`insufficient_scope`	The token lacks the scope this endpoint needs.
`not_found`	`not_found`	The resource doesn't exist.
`conflict`	`conflict`	A uniqueness or state conflict.
`rate_limited`	`rate_limited`	The rate limit was hit; honor `Retry-After`.
`service_unavailable`	`unavailable`	The endpoint is disabled or temporarily down.

This isn't the full set — new codes can appear over time, so branch on type (or the HTTP status) and treat code as an optional refinement. The exhaustive list lives in the OpenAPI spec.

REST API — conventions, authentication, pagination.
Interactive reference — every endpoint's request/response shapes.

Errors

Error types

Common codes

Related