Errors: request error codes and task failure codes

A request the API refuses returns an HTTP error status and this 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-10-19T04:12:00.000Z"
  }
}

code is stable; branch on it. message is for people and can change. details is present when there is something to add: usually an array of { field, message } for a validation error, or an object such as { "id": "..." } or { "retryAfterSec": 5, "retryable": true }. A task that is accepted and later fails does not produce an HTTP error. It reports a task failure code instead.

Request error codes

Code	Status	Meaning	Retry?
`VALIDATION_ERROR`	400	Malformed body, unknown `taskType`, a missing or invalid field, or an invalid `webhook.url`. `details` names the field.	No. Fix the request.
`VALIDATION_ERROR`	422	A well-formed request that breaks an engine-specific rule: a `WEB_SCRAPE`, `WEB_MAP` or `WEB_CRAWL` option, a `REDDIT` field, a `BING_SEARCH` text over 4,000 characters, `payload.page` outside 1 to 10, or `include.analysis` on an engine that does not support it.	No. Fix the request.
`USE_DEDICATED_ENDPOINT`	400	`CITATION_ANALYSIS`, `PROMPT_RESEARCH` or `GEO_SCORE` sent to `/v1/async/task`. Use `POST /v1/citation-analysis`, `POST /v1/prompt-research` or `POST /v1/geo-score`.	No
`CONVERSATION_EXPIRED`	400	The ChatGPT conversation in `payload.continueFrom` can no longer be continued.	No. Start a new task.
`MISSING_API_KEY`	401	The `Authorization` header is missing, or its key is unknown, expired or revoked.	No. Fix the key.
`INSUFFICIENT_CREDITS`	402	Your balance cannot cover the task’s hold.	After you add credits
`KEY_SCOPE_DENIED`	403	The engine is outside the key’s allowed engines.	No. Use another key or change its scope.
`ENGINE_PRIVATE`	403	The `taskType` is not available on self-serve plans. `details.availableTaskTypes` lists the ones that are.	No
`RESOURCE_NOT_FOUND`	404	Unknown task, batch, grid or place lookup id, another account’s id, or a task past the 24-hour polling window.	No
`NOT_FOUND`	404	No route for this method and path.	No
`RESOURCE_ALREADY_EXISTS`	409	Repeated `idempotencyKey` on `POST /v1/async/task`, a grid resent under the same id with other coordinates, or a place lookup resent under the same id for another store, country or engine list. See Idempotency.	No. The task exists.
`PAYLOAD_TOO_LARGE`	413	The body is over the endpoint’s limit (below).	No. Send less.
`REGION_UNSUPPORTED`	422	This engine never serves the requested `country`. `details.retryable` is `false`.	No. Pick another engine or country.
`LOCATION_UNSUPPORTED`	422	`payload.location` on an engine other than `CHATGPT`, `GEMINI`, `GOOGLE`, `AIMODE` or `GOOGLE_SERP`.	No. Remove `location` or change engine.
`EVIDENCE_UNSUPPORTED`	422	`include.html` on an engine other than `CHATGPT`, `GEMINI`, `PERPLEXITY`, `META_AI`, `BING_COPILOT`, `GOOGLE` or `AIMODE`, or on a `CHATGPT` task with a `location`, `CN`, `HK` or `continueFrom`.	No. Remove the flag or change engine.
`PLAN_CONCURRENCY_LIMIT`	429	Your queued and processing tasks reached your plan, contract or sub-account limit.	Yes, after `Retry-After`
`KEY_DAILY_CREDIT_LIMIT`	429	The key reached its daily credit limit.	After `Retry-After`, at the next midnight UTC
`SUB_ACCOUNT_CREDIT_LIMIT`	429	The task would take the sub-account over its `monthlyCreditLimit`. See Sub-accounts.	Next UTC month, or after the parent raises the limit
`QUEUE_BACKPRESSURE`	503	This engine’s queue is full.	Yes, after `Retry-After`
`SERVER_OVERLOADED`	503	Admission is saturated.	Yes, after `Retry-After`
`SERVER_OVERLOADED`	503	The global task queue is full.	Yes, after `Retry-After`
`ENGINE_UNAVAILABLE`	503	This engine is temporarily not accepting tasks.	Yes, after `Retry-After`
`DB_UNAVAILABLE`	503	Storage did not answer.	Yes, after `Retry-After`
`EVIDENCE_UNAVAILABLE`	503	HTML pages are not available on the server right now.	Later, or resubmit without `include.html`
`ENQUEUE_ERROR`	503	One item of a batch or grid could not be stored. Appears per item, not as the request status.	Yes
`INTERNAL_ERROR`	500	An unexpected server error.	Yes, with backoff

Prefer error.code over the status: VALIDATION_ERROR appears as both 400 and 422. A 429 means you reached one of your own limits; a 503 means we are short of capacity for the moment.

Retry-After

On POST /v1/async/task, POST /v1/async/task/batch and POST /v1/async/task/grid, every 429 and 503 carries a Retry-After header in seconds. Most of these codes also carry details.retryAfterSec and details.retryable: true. 429s from the edge request limit carry neither. See Credits and limits.

Payload size limits

Endpoint	Max body
`POST /v1/async/task`	1 MiB
`POST /v1/async/task/batch`	8 MiB
`POST /v1/batches`	32 MiB
`POST /v1/async/task/grid`	1 MiB
`POST /v1/citation-analysis`, `POST /v1/prompt-research`, `POST /v1/geo-score`, `POST /v1/product-lookup`	1 MiB

Region rejection

REGION_UNSUPPORTED is decided before the task is queued, so you learn at once instead of waiting for the task to fail:

{
  "success": false,
  "error": {
    "code": "REGION_UNSUPPORTED",
    "message": "PERPLEXITY cannot be served for country='CN' ...",
    "details": { "taskType": "PERPLEXITY", "country": "CN", "cause": "no_proxy_route", "retryable": false },
    "timestamp": "2026-10-19T04:12:00.000Z"
  }
}

Which engines serve which countries is on Regions and location.

Batch and grid per-item errors

On POST /v1/async/task/batch, a well-formed request returns 200 even when items fail. The status describes the request; results[].success describes each task, and a failed item carries the same { code, message, details, timestamp } object as a request error:

{
  "success": true,
  "summary": { "total": 2, "succeeded": 1, "failed": 1 },
  "results": [
    { "success": true, "index": 0, "task": { "...": "..." }, "credits": { "creditsToCharge": 0, "creditsCharged": 0 } },
    { "success": false, "index": 1, "error": { "code": "QUEUE_BACKPRESSURE", "message": "...", "details": { "retryAfterSec": 5, "retryable": true }, "timestamp": "2026-10-19T04:12:00.000Z" } }
  ]
}

An item that failed with a 429 code, QUEUE_BACKPRESSURE or SERVER_OVERLOADED carries its wait in details.retryAfterSec. The request itself fails with 400, 413, 429 or 503 only when the whole batch is refused. POST /v1/async/task/grid reports refused points the same way in points[]. POST /v1/batches rejects the whole batch with 400 if any item is invalid, and later marks items it cannot run as REJECTED, including API_KEY_INACTIVE when the batch’s key is revoked or expired. See Batches and grids.

Task failure codes

A task that fails after it was queued ends in FAILED. Polling returns a top-level error string, not the request-error object:

{
  "success": true,
  "task": { "id": "8f2c1e40-...", "status": "FAILED", "...": "..." },
  "credits": { "creditsToCharge": 0, "creditsCharged": 0 },
  "error": "ENGINE_TIMEOUT: The engine did not answer before the task deadline."
}

The webhook carries the same string in response.error. The string starts with a code; branch on it.

Code	Meaning	What to do
`ENGINE_TIMEOUT`	The engine did not answer before the task deadline.	Retry the task
`ENGINE_NO_RESULT`	The engine returned no usable result.	Retry, or rephrase the prompt
`NO_IP_AVAILABLE`, `NO_ACCOUNT_AVAILABLE`	No capacity was available for this engine and country in time.	Retry later
`CONVERSATION_EXPIRED`	The conversation can no longer be continued.	Start a new task
`BAD_PAYLOAD`	The engine could not use a field. The message names it.	Fix the field
`PAGE_UNAVAILABLE`	A page `WEB_SCRAPE`, `WEB_CRAWL`, `WEB_MAP` or Naver’s `page` action could not read, such as a members-only page or a site that refused the request. The message gives the site’s answer. For `GEO_SCORE`, no browser could show the page.	Change the URL
`CHATGPT_UNAVAILABLE`	`GEO_SCORE` received no answer from ChatGPT to its questions about the page.	Retry the task
Any other code	The engine could not complete the task.	Retry

WEB_CRAWL fails with PAGE_UNAVAILABLE when its start page cannot be read, and WEB_MAP when it finds no address on the site. Other pages a crawl could not read are listed in its failed field. A failed task is not charged.

Get started

Core concepts

Answer engines

Search and web data

Request options

Research

GEO monitoring

Account and data

Errors: request error codes and task failure codes

Request error codes

Retry-After

Payload size limits

Region rejection

Batch and grid per-item errors

Task failure codes

​Request error codes

​Retry-After

​Payload size limits

​Region rejection

​Batch and grid per-item errors

​Task failure codes

Request error codes

Retry-After

Payload size limits

Region rejection

Batch and grid per-item errors

Task failure codes