Core API
Errors & Status Codes
Understand the E2X JSON error envelope, HTTP status mapping (400, 401, 402, 403, 404, 409, 413, 429, 500, 503), X-Request-ID tracing, sanitized job errors, and retry strategies.
JSON Error Envelope & Tracing
All error responses return an HTTP 4xx or 5xx status code alongside a uniform JSON envelope. Every response also carries an X-Request-ID HTTP header matching requestId in the body.
{
"success": false,
"error": {
"code": "INVALID_INPUT",
"message": "Input validation failed",
"details": {
"errors": [
{ "path": "/resolution", "message": "must be equal to one of the allowed values" }
]
}
},
"requestId": "req_e2x_89ab10cf"
}Sanitized Async Job Errors
When an asynchronous job transitions to failed, job.error in GET /v1/jobs/:jobId and outbound webhooks is passed through sanitizeJobError: internal provider identifiers and raw upstream tracebacks are stripped so clients receive only safe code and message fields.
HTTP Status Codes & API Error Codes
| HTTP Status | Error Codes | Cause & Remediation |
|---|---|---|
400 Bad Request | VALIDATION_ERROR, INVALID_INPUT, INVALID_MODEL_SLUG, INVALID_WEBHOOK_URL, CONFLICTING_INPUT, GENERATIONS_LIMIT_EXCEEDED, MODEL_INACTIVE, MODEL_VERSION_NOT_ACTIVE, JOB_CANNOT_BE_CANCELLED, INVALID_JSON | Request syntax, JSON Schema inputs, webhook URL safety check, batch count (>16), or job state precondition failed. Fix request parameters before retrying. |
401 Unauthorized | UNAUTHORIZED, INVALID_API_KEY, API_KEY_INACTIVE, API_KEY_EXPIRED | Missing Authorization: Bearer header, unrecognized key hash, revoked/inactive key, or expired key. |
402 Payment Required | INSUFFICIENT_BALANCE | Wallet micro-cents balance is below estimated job cost. Top up balance in Billing before resubmitting. |
403 Forbidden | MODEL_NOT_ALLOWED, MODEL_ACCESS_DENIED, OPERATION_NOT_ALLOWED, IP_NOT_WHITELISTED, USER_BANNED, USER_INACTIVE, UNAUTHORIZED_ACCESS | Authenticated key or account lacks permission for the target model, operation scope, client IP, or job resource. |
404 Not Found | MODEL_NOT_FOUND, MODEL_VERSION_NOT_FOUND, JOB_NOT_FOUND | Target model slug, model version ID, or job ID does not exist. |
409 Conflict | COUPON_LIMIT_REACHED, COUPON_ALREADY_USED | Coupon quota reached or already redeemed. |
413 Payload Too Large | PAYLOAD_TOO_LARGE | Request body exceeded the 16 MB JSON limit. Use POST /v1/uploads/presign for large media inputs. |
429 Too Many Requests | RATE_LIMIT_EXCEEDED, CONCURRENT_JOBS_EXCEEDED, TOO_MANY_PENDING_UPLOADS | Request rate limit, active concurrent job limit, or 200-item pending upload cap exceeded. Wait for Retry-After or active jobs to finish. |
500 Internal Error | INTERNAL_ERROR, MODEL_PRICING_INVALID | Unexpected gateway or catalog pricing configuration failure. Retry with exponential backoff. |
503 Unavailable | PUBSUB_PUBLISH_FAILED, INPUT_OFFLOAD_FAILED | Transient queue publish or object-storage offload failure. No balance deduction remains pending when queue publish fails; safe to retry with backoff. |
Client Retry Strategy
Retry only idempotent reads (GET) and transient 429 / 503 / 500 failures with randomized backoff. Never blindly retry 400, 401, 402, 403, or 404 errors without fixing the underlying request or credentials.