Get started
Errors
Error envelope, status codes, and retry guidance.
Every error response uses a consistent envelope so clients can handle failures uniformly:
Error envelopejson
{
"statusCode": 404,
"error": "Not Found",
"message": "Job job_8f2 was not found",
"requestId": "req_01j9x3..."
}Status codes
| Code | Meaning | Retry? |
|---|---|---|
| 400 | Validation failed — message lists the offending fields | No |
| 401 | Missing or invalid credentials | No |
| 403 | Insufficient scope or plan feature | No |
| 404 | Resource not found or already deleted | No |
| 409 | Conflict — e.g. job already completed | No |
| 429 | Rate limited — respect Retry-After | Yes, after backoff |
| 5xx | Server error | Yes, with exponential backoff |
Retrying safely
- Retry 429 and 5xx with exponential backoff plus jitter (start ~1s, cap ~30s).
- Read the Retry-After header on 429 before retrying.
- Mutating endpoints accept an Idempotency-Key header — safe to retry without duplicating jobs.
- Include the requestId from the envelope when contacting support.
Was this page helpful?