WebScrapingAPI Docs

Errors and Headers

Authentication, validation, response header, and retry behavior for production integrations.

Authentication errors

StatusBodyMeaning
401Access denied. No key api_key provided.No API key was provided.
401Access denied. Invalid api_key provided.Browser/WebScrapingAPI received a key with invalid characters or more than 32 characters.
401{"error":"Authentication failure: ... Get a free API Key ... or upgrade your plan"}The key failed account authentication or is not entitled to the service.
429{"error":"max_concurrent_connections"}SearchData API concurrency limit was hit.
503{"error":"other_failure"}Authentication backend returned a transient failure.

Public integrations should always use api_key.

Validation errors

The APIs validate request parameters before they call a worker. Common validation messages include:

MessageCause
Parameter '<name>' not allowed.The parameter is not accepted by the selected endpoint or engine.
Parameter '<name>' is required.A required parameter is missing.
Parameter '<name>' must be a boolean.A boolean field was not parseable as 1, 0, true, or false.
Parameter '<name>' must be in range ...Numeric value is outside the endpoint's allowed range.
Parameter '<a>' cannot be used with parameter '<b>'.Mutually exclusive fields were combined.
Invalid URLurl did not decode to a valid URL.

For SearchData /v1 and SERP /v2, the selected engine controls the allowed parameters.

Website and scraping errors

StatusShapeMeaning
422error_type: "website"The target site returned an invalid body, a CAPTCHA challenge, a timeout, or an error status.
500status: "Internal Server Error"The API handler threw an unexpected error.
502JSON body with retry messageAsync submission returned an invalid scraping response.

Retry 422 and 502 failures with backoff when the request is idempotent. Do not blindly retry 401 or validation errors.

Response headers

HeaderAPIMeaning
WSA-Scraped-Headers/v1, /v2JSON string of headers returned by the scraping request.
WSA-Scraped-Resolved-Url/v1, /v2Final URL after redirects when available.
WSA-Client-Cookies/v1Browser cookies captured after navigation.
set-cookie/v1, /v2Target set-cookie header forwarded when present.
Searchdata-Call-Credit-UsageSearchData/SERPCredits charged for the call. Failed SearchData responses set this to 0.
Searchdata-Current-Credit-UsageSearchData/SERPCurrent account credit usage from the API handler.

Retry guidance

Use exponential backoff with jitter for transient failures:

CaseRetry?Notes
429YesSlow down concurrent requests before retrying.
500, 502, 503YesRetry a small number of times with backoff.
422 website errorsSometimesRetry only if the target failure is likely transient.
401NoFix authentication or plan entitlement.
Validation errorsNoFix the request payload.

For async flows, poll every 10 to 30 seconds and cap total waiting time in your application. Store completed async results in your own system instead of repeatedly polling old snapshot ids.

On this page