Errors and Headers
Authentication, validation, response header, and retry behavior for production integrations.
Authentication errors
| Status | Body | Meaning |
|---|---|---|
401 | Access denied. No key api_key provided. | No API key was provided. |
401 | Access 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:
| Message | Cause |
|---|---|
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 URL | url did not decode to a valid URL. |
For SearchData /v1 and SERP /v2, the selected engine controls the allowed parameters.
Website and scraping errors
| Status | Shape | Meaning |
|---|---|---|
422 | error_type: "website" | The target site returned an invalid body, a CAPTCHA challenge, a timeout, or an error status. |
500 | status: "Internal Server Error" | The API handler threw an unexpected error. |
502 | JSON body with retry message | Async 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
| Header | API | Meaning |
|---|---|---|
WSA-Scraped-Headers | /v1, /v2 | JSON string of headers returned by the scraping request. |
WSA-Scraped-Resolved-Url | /v1, /v2 | Final URL after redirects when available. |
WSA-Client-Cookies | /v1 | Browser cookies captured after navigation. |
set-cookie | /v1, /v2 | Target set-cookie header forwarded when present. |
Searchdata-Call-Credit-Usage | SearchData/SERP | Credits charged for the call. Failed SearchData responses set this to 0. |
Searchdata-Current-Credit-Usage | SearchData/SERP | Current account credit usage from the API handler. |
Retry guidance
Use exponential backoff with jitter for transient failures:
| Case | Retry? | Notes |
|---|---|---|
429 | Yes | Slow down concurrent requests before retrying. |
500, 502, 503 | Yes | Retry a small number of times with backoff. |
422 website errors | Sometimes | Retry only if the target failure is likely transient. |
401 | No | Fix authentication or plan entitlement. |
| Validation errors | No | Fix 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.