Errors

Every V1 API error returns a consistent JSON envelope. Branch your integration on the stable error.code — never parse the human-readable error.message, which is not a contract and may change.

Error envelope

{
  "error": {
    "code": "scope_insufficient",
    "message": "The token is missing a required scope.",
    "requestId": "req_a1b2c3d4",
    "timestamp": "2026-06-21T10:32:00.000Z",
    "details": [{ "field": "scope", "message": "tasks:write required" }]
  }
}

Handling errors

1. Read the HTTP status for the broad class (4xx client, 5xx server).
2. Switch on error.code for precise handling (e.g. refresh on unauthorized, back off on rate_limit_exceeded, request the missing scope on scope_insufficient).
3. Log requestId so support can trace the exact request.

The exception filter clamps every emitted code to the catalog: a code that is not yet enumerated falls back to its status-map generic (e.g. bad_request), so you can always rely on the code being one of the catalogued values.

Full catalog

The complete, always-current list — code, HTTP status, and category — is generated from the @emofy/types error-code SSOT:

→ Error Catalog