Errors

Failures share one envelope:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [{ "field": "payload.prompt", "message": "payload.prompt or payload.query is required" }],
    "timestamp": "2026-07-09T04:12:00.000Z"
  }
}

code is stable and safe to branch on. message is for humans and may change. details is present when we can name the offending field.

Codes

Code	Status	Meaning	Retry?
`MISSING_API_KEY`	401	Missing or wrong bearer token.	No — fix the key
`VALIDATION_ERROR`	400	Malformed body, unknown `taskType`, or neither `payload.prompt` nor `payload.query` present.	No — fix the request
`REGION_UNSUPPORTED`	422	This engine can never serve the requested `country`.	No — pick another engine or region
`REGION_UNAVAILABLE`	422	No capacity for the requested `country` on this engine right now.	Later, after capacity returns
`RESOURCE_ALREADY_EXISTS`	409	Duplicate `idempotencyKey` on the single-task endpoint.	No — the task already exists
`PAYLOAD_TOO_LARGE`	413	Batch body exceeds 8 MB.	No — send smaller chunks
`RESOURCE_NOT_FOUND`	404	Task id unknown, or the task passed the 24-hour public polling window.	No
`ENQUEUE_ERROR`	—	Per-item failure inside a batch (e.g. a database hiccup on one lane). Appears in `results[].error`, never as an HTTP status.	Yes

400 is for a request we cannot parse or understand. 422 is reserved for a request that is perfectly well-formed but that we cannot serve for the requested region. Branching on error.code is more durable than branching on the status.

Region rejections

Both region codes are decided before the task is queued, so you learn immediately instead of watching a task burn its whole retry budget and fail with a symptom-shaped error. REGION_UNSUPPORTED is permanent — that engine cannot serve the requested country:

{
  "success": false,
  "error": {
    "code": "REGION_UNSUPPORTED",
    "message": "GEMINI cannot be served for country='DE'. This is a permanent capability gap — retrying will not help. GOOGLE and AIMODE remain available for this country.",
    "details": { "taskType": "GEMINI", "country": "DE", "retryable": false },
    "timestamp": "2026-07-09T04:12:00.000Z"
  }
}

See the table of unserveable combinations. REGION_UNAVAILABLE is transient — the route exists but nothing can serve it at the moment. Query GET /capacity to see what each region can currently serve.

Batch failures are per-item

A well-formed batch always returns 200, even if every task inside it failed. The HTTP status describes the request; results[].success describes each task.

{
  "success": true,
  "summary": { "total": 3, "succeeded": 2, "failed": 1 },
  "results": [
    { "success": true,  "index": 0, "task": { "...": "..." } },
    { "success": false, "index": 1, "error": { "code": "REGION_UNAVAILABLE", "message": "..." } },
    { "success": true,  "index": 2, "task": { "...": "..." } }
  ]
}

Only a malformed request as a whole — non-JSON, not an array, empty, over 500 items, over 8 MB, or unauthorized — produces a 4xx for the batch itself.

A batch item can fail with REGION_UNAVAILABLE or ENQUEUE_ERROR, neither of which appears in the per-item error enum of the async task contract this API implements. Both are additions, not replacements — VALIDATION_ERROR and RESOURCE_ALREADY_EXISTS are unchanged.

Task-level failures

A task that fails after being queued does not produce an HTTP error at all. You learn about it from the terminal status:

{
  "success": true,
  "task": { "id": "8f2c1e40-...", "status": "FAILED", "...": "..." },
  "credits": { "creditsToCharge": 0, "creditsCharged": 0 },
  "error": "engine timeout after 3 attempts"
}

Note the shape difference: this top-level error is a string, not the {code, message, timestamp} object used by request-level errors. It is the last engine error recorded before the task gave up. The same task delivers a webhook with task.status === "FAILED".

Get started

Core concepts

Engines

Source Influence

GEO Monitoring

Migrating

Codes

Region rejections

Batch failures are per-item

Task-level failures

​Codes

​Region rejections

​Batch failures are per-item

​Task-level failures

Codes

Region rejections

Batch failures are per-item

Task-level failures