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_UNAVAILABLE`	422	No account or IP capacity for the requested `country` on this engine.	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 aged out of the 24-hour retention 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 process right now — today that means REGION_UNAVAILABLE alone. Branching on error.code is more durable than branching on the status.

Region unavailability

CHATGPT and CLAUDE draw on pools of real accounts that are bound to a region. Before queuing, the API checks whether it can actually serve payload.country (defaulting to US) and rejects up front if it cannot:

{
  "success": false,
  "error": {
    "code": "REGION_UNAVAILABLE",
    "message": "cannot serve region 'DE': no live IPs provisioned. Check GET /capacity.",
    "details": { "country": "DE", "serveable": 0, "hasIps": false },
    "timestamp": "2026-07-09T04:12:00.000Z"
  }
}

This is a deliberate fast failure. Without it the task would be accepted and then spin, failing to acquire an account until it exhausted its retries — a slow, expensive way to learn the same thing. Query GET /capacity to see what each region can currently serve. Every other engine is stateless from an account perspective and is never rejected this way.

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 Cloro’s documented per-item error enum. Both are additions, not replacements — VALIDATION_ERROR and RESOURCE_ALREADY_EXISTS behave as Cloro specifies.

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

Migrating

Codes

Region unavailability

Batch failures are per-item

Task-level failures

​Codes

​Region unavailability

​Batch failures are per-item

​Task-level failures

Codes

Region unavailability

Batch failures are per-item

Task-level failures