All errors use a consistent JSON envelope. HTTP status codes follow standard semantics. Failed async jobs also embed an error object on the job resource when status is failed.
Error envelope
{
"error": {
"code": "validation_error",
"message": "image is required.",
"details": {
"image": ["The image field is required."]
}
}
}
HTTP status map
| Status | Meaning |
|---|
| 401 | Missing or invalid API key |
| 403 | Client suspended or module not allowed |
| 404 | Unknown endpoint, module, or job |
| 422 | Validation failed |
| 429 | Rate limit, request quota, or credits exceeded |
| 500 / 502 | Unexpected processing failure — retry with backoff |
Error codes
| Code | Description |
|---|
| unauthorized | Missing or invalid API key. |
| forbidden | The API key is not allowed to access this resource. |
| module_not_allowed | This module is not enabled for your API client. |
| quota_exceeded | Monthly request quota has been reached. |
| credits_exceeded | Monthly credit allowance has been reached. |
| rate_limited | Too many requests. Retry after the indicated delay. |
| validation_error | One or more request fields failed validation. |
| not_found | The requested resource does not exist. |
| job_failed | The job completed with an error. |
| processing_error | The request could not be processed. |
| service_unavailable | Temporary service interruption. Retry with backoff. |
Retries
- Retry
429 and 5xx with exponential backoff. Honor Retry-After when present. - Do not retry
401, 403, or 422 without changing the request. - Idempotency: creating a job always starts a new run. Store the returned job id before polling.