Skip to main content

​
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

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

​
Error code index

CodeStatusDescription
invalid_request400Request schema validation failed.
missing_api_key401Authorization header is absent.
invalid_api_key401API key not found or revoked.
credits_exhausted402Tenant credit balance is zero.
idempotency_conflict409Idempotency key reused with a different body.
extraction_failed422LLM or selector extraction produced no usable output.
extraction_validation_error422Extracted data failed schema validation.
target_blocked502The target URL rejected or blocked the request.
blocked_by_amazon502Amazon’s bot-protection blocked the request.
timeout504The fetch or interaction exceeded timeout_ms.
proxy_unavailable503No usable proxy is available for this request.
daily_credit_cap_exceeded429Per-tenant daily cap reached.
job_not_found404The job_id does not exist or has expired.
job_not_ready409The job has not finished; check status first.