Responses and errors

Error shape

Branch on type, not on translated human-readable messages.

{
  "type": "FORBIDDEN",
  "data": null
}

Common HTTP statuses

• 401 — missing, invalid, expired, revoked PAT, or workspace PAT access disabled. All return exactly {"type":"UNAUTHORIZED"} with no data or reason, so they cannot be distinguished
• 403 — authenticated request lacks permission for the resource in the current role
• 404 — resource missing or outside the user's access
• 409 — record state conflict
• 422 — path or query validation failed

Troubleshooting order

1. 1

   Record the HTTP status and type

   Remove raw PATs and download URLs from logs.

2. 2

   Check identifiers

   Confirm that workspace slug, record_id, team_id, and member_id belong together.

3. 3

   Check current access

   Verify that the same user can see the resource in Callabo. A 401 for one workspace does not distinguish a PAT problem from PAT access disabled for that workspace.