API errors

The Web Scraping API returns standard HTTP status codes. Non-2xx responses include a JSON body with an error field describing what went wrong.

Error codes

Code	Meaning
400	Bad Request. The request is malformed or has invalid parameters. Also returned when the target URL could not be scraped.
401	Unauthorized. The API key is missing, invalid, or the credit quota is exceeded.
403	Forbidden. Your plan does not include this feature (for example JavaScript rendering or country-specific geolocation). Upgrade your subscription to use it.
406	Not Acceptable. The requested response format is not supported.
422	Unprocessable Entity. The request was valid but could not be fulfilled. Common causes: the target site returned a CAPTCHA under a 200 OK, the response HTML is empty, an Instagram profile returned the login page, or a wait_for_css selector never appeared.
429	Too Many Requests. You are sending requests too quickly or running too many in parallel. Google may also return this when it detects the scraper.
500	Internal Server Error. Something broke on our side. Try again shortly.
503	Service Unavailable. The API is temporarily offline for maintenance. Try again later.

Retry semantics

Note

422 and 5xx responses are safe to retry after a short backoff. 4xx responses other than 429 usually indicate a client-side issue that retrying will not fix.

• Retry 500 and 503 with exponential backoff (for example 1s, 2s, 4s).
• Retry 429 after a pause, and reduce request concurrency.
• Do not retry 400, 401, 403, or 406 without changing the request.

See also

• Web Scraping API - endpoint hub
• Basic request - minimal call example