Error Handling
Web DataThe 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 |
403 | The target is on Geonode's compliance blocklist. Nothing was sent to it and nothing is charged. | Extract |
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 ran out of time: the request's timeout or the 140-second limit. Not charged. 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_URLINVALID_WAIT_FOR_SELECTORWAIT_FOR_SELECTOR_TIMEOUTUNPROCESSABLE_CONTENTAUTH_REQUIREDTIMEOUTCANCELLEDPAYMENT_REQUIREDINTERNAL_ERRORPROXY_ERRORTARGET_BLOCKED
Use the retryable field to decide whether a retry may help. For retryable failures, use exponential backoff and avoid retrying in a tight loop.
What Some Codes Mean
| Code | Meaning |
|---|---|
UNPROCESSABLE_CONTENT | The site answered, but not with the page content. Usually this is a Cloudflare or similar challenge that could not be passed, and the message names the detected challenge. It is also returned for an empty page, a file download, or a target that cannot be served at all (then retryable is false). |
CAPTCHA_CHALLENGE | Reserved. Challenge pages currently come back as UNPROCESSABLE_CONTENT. |
TIMEOUT | A sync request ran out of time: its timeout or the 140-second limit. Returned with 504 and not charged. For slow pages, use async mode. |
CANCELLED | The client disconnected before a sync request finished. Not charged. |
Check tokens_charged in the error response to see what was charged.
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.
Was this page helpful?