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.

JSONStandard Error Response Shape
{
  "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 StatusError CodesCause & Remediation
400 Bad RequestVALIDATION_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_JSONRequest syntax, JSON Schema inputs, webhook URL safety check, batch count (>16), or job state precondition failed. Fix request parameters before retrying.
401 UnauthorizedUNAUTHORIZED, INVALID_API_KEY, API_KEY_INACTIVE, API_KEY_EXPIREDMissing Authorization: Bearer header, unrecognized key hash, revoked/inactive key, or expired key.
402 Payment RequiredINSUFFICIENT_BALANCEWallet micro-cents balance is below estimated job cost. Top up balance in Billing before resubmitting.
403 ForbiddenMODEL_NOT_ALLOWED, MODEL_ACCESS_DENIED, OPERATION_NOT_ALLOWED, IP_NOT_WHITELISTED, USER_BANNED, USER_INACTIVE, UNAUTHORIZED_ACCESSAuthenticated key or account lacks permission for the target model, operation scope, client IP, or job resource.
404 Not FoundMODEL_NOT_FOUND, MODEL_VERSION_NOT_FOUND, JOB_NOT_FOUNDTarget model slug, model version ID, or job ID does not exist.
409 ConflictCOUPON_LIMIT_REACHED, COUPON_ALREADY_USEDCoupon quota reached or already redeemed.
413 Payload Too LargePAYLOAD_TOO_LARGERequest body exceeded the 16 MB JSON limit. Use POST /v1/uploads/presign for large media inputs.
429 Too Many RequestsRATE_LIMIT_EXCEEDED, CONCURRENT_JOBS_EXCEEDED, TOO_MANY_PENDING_UPLOADSRequest rate limit, active concurrent job limit, or 200-item pending upload cap exceeded. Wait for Retry-After or active jobs to finish.
500 Internal ErrorINTERNAL_ERROR, MODEL_PRICING_INVALIDUnexpected gateway or catalog pricing configuration failure. Retry with exponential backoff.
503 UnavailablePUBSUB_PUBLISH_FAILED, INPUT_OFFLOAD_FAILEDTransient 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.