Error Responses

Errors set meta.status to "error" and populate meta.errors with one entry per problem:

{
  "meta": {
    "status": "error",
    "errors": [
      {
        "message": "Workspace not found",
        "status_code": 404,
        "error_code": "not_found",
        "occurred_at": "2026-08-05T12:00:00Z"
      }
    ],
    "warnings": []
  }
}

occurred_at, error_code, and error_metadata are optional and may be null — key off status_code and message first.

Code	Meaning	When it happens
400	Bad Request	An application-level validation rule failed — not a schema/type error, but a business rule (e.g. a value out of range, an inferred setting with no valid value).
401	Invalid token	The bearer token fails gateway-level verification — wrong issuer/key-id, wrong signing algorithm, bad signature, failed claims, or an empty subject.
403	Forbidden	Any authentication or authorization failure — missing/invalid credential, a PAT used against a workspace outside its scope, insufficient permission, or a workspace_id/group_id/etc. that doesn't exist or isn't visible to this token. These deliberately share one generic message — the API does not reveal which case applies.
404	Not Found	A specific named resource wasn't found within a scope you can otherwise access — distinct from the 403 case above, which covers the scope itself (e.g. the workspace_id) being inaccessible. Also returned for a request path that doesn't match any route.
405	Method Not Allowed	Valid path, wrong HTTP verb (e.g. PUT on a route that only defines GET/POST).
409	Conflict	Trying to create something that already exists in a way that would collide — a duplicate attribute-definition name in a workspace, an attribute already set on this group/member, or an existing group membership.
422	Unprocessable Entity	The request itself doesn't match the expected shape — malformed JSON, a required field missing, or a field of the wrong type — caught by schema validation before any application logic runs.
429	Too Many Requests	Rate limit exceeded.
500	Internal Server Error	An unexpected, unhandled error. The message is always the same generic string — no internal detail is ever leaked to the client.