Errors
The error response shape, status codes, and how to handle them.
When a request fails, the API returns a JSON body with an error field describing what went wrong. Building this into your integration up front makes failures easy to log and act on.
Error shape
Most errors look like this:
{ "error": "Project not found." }Validation errors use a fixed error value and add a details array describing each problem, so you can show field-level feedback:
{
"error": "ValidationError",
"details": [{ "path": ["dueDate"], "message": "Invalid date" }]
}Status codes
| Status | Meaning | What to do |
|---|---|---|
| 400 | Invalid input, route parameter, or query parameter | Fix the request; check details for the failing field |
| 401 | Missing or invalid bearer token | Re-authenticate or refresh the access token |
| 402 | Not enough credits for a credit-gated operation | Add credits, then retry (see Credits) |
| 403 | Authenticated but not allowed in the selected scope or workspace | Check the workspace context and the caller's permissions |
| 404 | Requested record or reference was not found | Verify the ID, alias, or reference |
| 409 | Conflict, such as an invalid state transition or duplicate constraint | Reconcile state before retrying |
| 429 | Rate limited (most often on OTP creation) | Back off and retry later |
| 500 | Unexpected server error | Retry with backoff; report if it persists |
| 502 | An upstream service returned an invalid or failed response | Retry with backoff |
Retry guidance
Retry only 429 and transient 5xx responses, and always use exponential backoff. Do not retry 4xx errors such as 400, 401, 403, 404, or 409 without first changing the request; they will fail again the same way.