Conventions
Errors
Standard status codes, and messages that name the fix.
Errors are JSON with a human-readable error, and sometimes a stable code to branch on. The message names the fix: a missing scope says which scope.
json
{ "error": "This token does not hold \"work.write\"." }| Status | Meaning |
|---|---|
400 | The request was malformed or failed validation. |
401 | No token, or one that is unknown, expired or revoked. |
403 | The token lacks the scope, or the person behind it lacks the permission. |
404 | Not found — including anything in another workspace, so ids never confirm what exists elsewhere. |
409 | It conflicts with the current state. |
422 | Understood, but a rule refused it. |
429 | Rate limited. Respect Retry-After. |
5xx | Our fault. Retry with backoff. |
Check the body, not only the status
Some older endpoints still report a refusal as
200 with an error field. Until they are all moved to real status codes, treat any response with an error key as a failure.