Errors

All errors share a single envelope. Top-level errors mean the whole call failed; per-URL errors inside /batch and /crawl use the same shape.

Envelope

{
  "status": "error",
  "error": {
    "code": "FETCH_BLOCKED",
    "message": "Both plain fetch and stealth headless were blocked.",
    "retryable": true
  }
}

Field	Notes
code	Machine-readable code from the table below
message	Human-readable detail; do not parse
retryable	If true, the same call can succeed on retry. If false, retrying will fail the same way

Codes

Schema & Request Shape

Code	HTTP	Retryable
SCHEMA_INVALID	400	no
SCHEMA_REQUIRED	422	no
SCHEMA_NOT_ALLOWED	400	no
TYPE_COERCION_FAILED	200	no

Quotas & Access

Code	HTTP	Retryable
RATE_LIMITED	429	yes (after Retry-After)
QUOTA_EXCEEDED	429	no this month
TIER_REQUIRED	402	no
KEY_LIMIT_REACHED	429	no
ACCOUNT_SUSPENDED	403	no

Fetch & Rendering

Code	HTTP	Retryable
FETCH_BLOCKED	200	yes
URL_UNREACHABLE	200	yes
TIMEOUT	200	yes

Crawl

Code	HTTP	Retryable
CRAWL_LIMIT_REACHED	200	n/a

LLM

Code	HTTP	Retryable
LLM_ERROR	200	yes
LLM_UNAVAILABLE	200	yes (back off)
LLM_RATE_LIMITED	200	yes (back off)
LLM_TIMEOUT	200	yes
LLM_TRUNCATED	200	yes
LLM_BLOCKED	200	no
LLM_EMPTY	200	yes
LLM_BAD_REQUEST	200	no

Jobs

Code	HTTP	Retryable
JOB_CANCELLED	n/a	n/a
JOB_NOT_FOUND	404	no
JOB_FORBIDDEN	403	no

For retry strategy guidance, see Errors & Retries.