Errors
Errors use standard HTTP status codes and one JSON body:
json
{
"code": "insufficient_scope",
"message": "This operation requires scope 'cases:write'.",
"requestId": "3f1c9a52-7c1e-4f3e-9d2a-0b8e5f6a1c44"
}| Status | Meaning | What to do |
|---|---|---|
| 400 | Invalid request or JSON | Fix the request; see message and details. |
| 401 | Missing, expired, or invalid token | Get a new token. The WWW-Authenticate header explains why. |
| 403 | Token lacks the required scope | Add the scope to your application and request a new token. |
| 404 | No such resource or operation | Check the path and identifier. |
| 409 / 428 | Version conflict / missing If-Match | Re-read the resource and retry with its current version. |
| 422 | Business rule violation | For example an invalid status transition. |
| 429 | Rate limit or daily quota reached | Wait for Retry-After seconds. Use exponential backoff with jitter. |
| 5xx | Server or upstream error | Retry idempotent calls with backoff; contact support with the request ID. |
Rate limits
Responses include X-RateLimit-Limit and X-RateLimit-Remaining (calls left today, UTC). Sandbox quotas depend on your plan; you can watch usage on Plan & billing.