Errors - Scrapio

Error envelope

All error responses share the same JSON shape:

{
  "request_id": "a1b2c3d4-e5f6-...",
  "error": {
    "code": "invalid_request",
    "message": "url is required"
  }
}

Some errors include a diagnostics object with additional context (e.g. whether the error is retryable, or whether the target blocked the request).

{
  "request_id": "...",
  "error": { "code": "target_blocked", "message": "The target site blocked the request." },
  "diagnostics": {
    "outcome": "failed",
    "retryable": false,
    "blocked": true
  }
}

HTTP status codes

Status	Meaning
`200`	Success — inline result returned.
`202`	Accepted — async job queued; poll `/v1/jobs/{id}` for the result.
`400`	Bad request — malformed or invalid parameters.
`401`	Unauthorized — missing or invalid API key.
`402`	Payment required — credit balance is zero.
`409`	Conflict — idempotency key already exists with a different request body.
`422`	Unprocessable — extraction or validation logic failed on the fetched content.
`429`	Too many requests — upstream rate limit hit.
`502`	Bad gateway — the target site blocked or rejected the request.
`503`	Service unavailable — execution backend (browser, proxy) is unavailable.
`500`	Internal server error — unexpected error; always retryable.

Error code index

Code	Status	Description
`invalid_request`	400	Request schema validation failed.
`unauthorized`	401	`Authorization` header is absent, or the API key wasn’t recognized.
`credits_exhausted`	402	Tenant credit balance is zero.
`plan_upgrade_required`	402	Endpoint requires a higher plan tier (Google SERP search needs Pro+; Amazon, Walmart, Booking.com, Agoda, and Fast Search need Starter+).
`idempotency_conflict`	409	Idempotency key reused with a different body.
`schema_validation_failed`	422	`extract.mode: "schema"` could not resolve one or more requested fields.
`instruction_limits_exceeded`	422	`extract.mode: "instruction"` exceeded the field/token limits for a single instruction.
`llm_unavailable`	422	LLM-based extraction was requested but no LLM provider is configured or reachable.
`selectors_unsupported`	422	`extract.mode: "selectors"` was used with a selector or field type the extractor doesn’t support.
`target_blocked`	502	The target URL rejected or blocked the request.
`free_plan_proxy_required`	502	The Free plan’s direct/stealth/gateway access methods were exhausted; this target likely needs proxy access, which Free doesn’t include. Upgrade to a paid plan.
`blocked_by_amazon`	502	Amazon’s bot-protection blocked the request.
`timeout`	504	The fetch or interaction exceeded `timeout_ms`.
`proxy_unavailable`	503	No usable proxy is available for this request.
`job_not_found`	404	The `job_id` does not exist or has expired.
`job_not_ready`	409	The job has not finished; check status first.