Error Handling
Understand Scraper API HTTP status codes and error response shapes.
The Scraper API returns standard HTTP status codes and JSON error bodies. Handle both validation errors and extraction errors in your client, because a request can fail before extraction starts or after the API tries to process the target page.
HTTP Status Codes
| HTTP status | Meaning | Returned by |
|---|---|---|
200 | Synchronous extraction, map request, job lookup, statistics request, webhook lookup, or health check succeeded. | Extract (sync), map, get job, get batch/crawl status, list jobs, statistics, webhook get/list, health |
201 | Webhook subscription was created. | Create webhook |
202 | Async extraction, batch, or crawl job was accepted, or a running job cancellation was accepted. | Extract (async), create batch, create crawl, cancel batch, cancel crawl |
204 | Webhook subscription was deleted. | Delete webhook |
400 | Invalid request. | Extract, map |
401 | API key is missing or invalid. | All authenticated endpoints |
402 | Payment required or insufficient request balance. | Extract, map, crawl |
404 | Job, webhook, or other requested resource was not found. | Get job, get batch/crawl status, cancel batch/crawl, webhook get/update/delete/deliveries |
408 | Map request timed out during URL discovery. | Map |
409 | Batch or crawl job cannot be cancelled in its current state. | Cancel batch, cancel crawl |
422 | Validation error or extraction failed. | Extract (body validation and extraction errors), create batch, create crawl, create/update webhook |
429 | Request throttled or work concurrency limit reached. | Extract, create batch, create crawl, map |
500 | Internal server error. | Extract, map, webhook create/get/update/delete/list/deliveries |
502 | Billing service returned an upstream error. Retryable depends on the billing error. | Extract, map, create crawl |
503 | Service or billing service temporarily unavailable. | Extract, map, create batch, create crawl |
504 | Synchronous extraction timed out waiting for the browser worker. Retryable. | Extract (sync) |
Validation Error
Validation errors can return a detail array. This usually means the request body does not match the expected schema, such as an invalid URL or unsupported value.
{
"detail": [
{
"type": "value_error",
"loc": ["body", "url"],
"msg": "Value error, URL must contain a valid hostname.",
"input": "not-a-url"
}
]
}Extraction Error
Extraction failures return an error object and tokens_charged.
{
"error": {
"code": "UNPROCESSABLE_CONTENT",
"message": "The target page could not be extracted.",
"retryable": false,
"details": null
},
"tokens_charged": 0
}The response field is currently named tokens_charged in the API schema. In Scraper API docs and billing language, treat this value as the number of requests charged.
Extraction Error Codes
Extraction error codes include:
RATE_LIMITEDWORK_CONCURRENCY_LIMITEDWORK_CONCURRENCY_LEASE_EXPIREDTEMPORARY_BLOCKNETWORK_ERRORCAPTCHA_CHALLENGEPERMANENT_BLOCKINVALID_URLUNPROCESSABLE_CONTENTAUTH_REQUIREDTIMEOUTPAYMENT_REQUIREDINTERNAL_ERRORPROXY_ERROR
Use the retryable field to decide whether a retry may help. For retryable failures, use exponential backoff and avoid retrying in a tight loop.
The OpenAPI schema includes 429 responses, but no public numeric rate limit is specified in the current contract. If you receive 429, slow down the client and retry after a delay.