API v2 errors and HTTP status codes
Use the HTTP status and response body together to diagnose a ScrapingAnt failure. This reference covers API v2; API v1 errors and Python/JavaScript SDK errors have version-specific behavior.
Error Responses
ScrapingAnt-generated failures use an HTTP status and a JSON detail string. The selected routes do not return a separate numeric ScrapingAnt error-code field. For example, this source-backed validation fixture has HTTP 422:
{
"detail": "Wrong host part of url. Please check out the documentation: https://docs.scrapingant.com/"
}
The outer HTTP status belongs to the request to ScrapingAnt. A target website's status is a different layer: a successful /v2/general response has HTTP 200 and exposes the target status in Ant-page-status-code; /v2/extended exposes it in the JSON status_code field. A target 404, 403 or 500 in those fields is not a ScrapingAnt error code. Check the returned content before treating an outer 200 as a useful result. See extended JSON responses.
A network exception without an HTTP response is a transport failure. An SDK exception may replace the API's message; use the SDK mapping before diagnosing by exception name alone.
Error Codes
These are HTTP statuses, not an exhaustive list of every gateway or target error. Follow the matching diagnosis below.
| HTTP status | Diagnosis | Retry the unchanged request? |
|---|---|---|
403 | Invalid token, credits or IP whitelist | No; resolve the matching access condition. |
404 | Unreachable site or worker timeout | Only after checking reachability/settings; bounded retries for a temporary failure. |
405 | Unsupported API method | No; correct the method. |
409 | Free user concurrency limit | Wait for the active request to finish, then send one request. |
422 | Missing token or invalid parameter | No; correct the input first. |
423 | Target-site detection | Only a bounded retry or a deliberate settings change. |
500 | Server or extraction failure | Bounded retries for safe operations; escalate if persistent. |
API v1 additionally returns 400 for malformed JSON input. In v2, request parameters are in the query string and the request body is forwarded to the target; a non-JSON body alone is not that v1 error. See request methods.
403: API token, requests quota and IP access
HTTP 403 has three distinct messages. Do not replace a valid key just because an SDK says the token is wrong.
Invalid key — exact detail:
API token is wrong. Please visit https://app.scrapingant.com/profile to check your token settings
Compare the key used by your application with your profile. Check for whitespace, a placeholder or a stale environment value. If both a header and query key are sent, the header takes precedence. Correct the application's value locally; do not put the key in logs or a support message. A missing key instead returns HTTP 422 with API token is missing. Please check out the documentation: https://docs.scrapingant.com/.
Credit allowance — exact detail:
Requests quota limit reached. Please visit https://app.scrapingant.com/subscriptions to upgrade your plan and get more requests
Check the remaining allowance and period in subscription status or your dashboard. Pause requests until an allowance is available; select a suitable plan if needed. Changing URL, proxy or key formatting does not restore credits.
IP restriction — exact detail:
Access denied from this IP address. Please visit https://app.scrapingant.com/whitelist to manage your IP whitelist settings
Check the outgoing public IP of the machine or deployment making the API call against your configured IP whitelist. A laptop and hosted worker may use different egress IPs. Have your account owner correct the intended allowed IP; do not disable restrictions as a troubleshooting shortcut. proxy_country selects the target-side proxy and does not change your application's IP for this access check.
Confirm the fix: one intentional request should stop returning the same 403. Then check the target status and content. Retries before the access condition changes will not resolve it.
409: Free user concurrency limit reached
Exact detail:
Free user concurrency limit reached. Please visit https://app.scrapingant.com/subscriptions to upgrade your plan and get more requests
The free plan allows one active request; paid plans have no concurrency limit. Check overlapping tasks, scheduled jobs, duplicate submissions and application retries using the same account. Queue free-plan work and wait for each response before starting the next. A client-side timeout does not prove the server finished, so avoid immediately starting replacement requests.
Confirm the fix: run requests sequentially and check that 409 disappears. Queueing is the primary fix; a retry loop that keeps overlapping requests repeats the condition. Python 2.1.0 has no dedicated 409 exception and may show KeyError: 'html' instead; see Python SDK errors.
422 and 405: request validation
Read detail to identify the parameter. Application validation messages append this literal suffix: Please check out the documentation: https://docs.scrapingant.com/. The phrases below precede that suffix unless noted.
| Message or template | Cause and fix |
|---|---|
url param is required. / Url can not be empty string. | Supply one nonempty target url query parameter. |
Wrong host part of url. / Missing host part of url. / Invalid url scheme, use http:// or https://. | Check the host and scheme. Use a complete public HTTP(S) URL, and encode it once as a query value. |
Invalid url format: {parser_error} | Template: the parser's diagnostic varies. Check malformed host/port syntax; remove private URL values before sharing the diagnostic. |
Invalid browser param value. / Invalid return_page_source param value. | Use a supported boolean such as true or false. Page-source mode requires the browser for its intended behavior. |
Invalid proxy_type param value. | Use datacenter or residential; check proxy settings. |
proxy_country is not a valid enumeration member; permitted: {countries} | Template: the available list is dynamic. Choose a country from the returned list/current reference. temporarily unavailable means the list could not be obtained; wait and escalate if persistent. |
Invalid timeout param value. Must be an integer number of seconds. | Supply integer seconds; a client network timeout and this API parameter are different settings. |
Timeout param value must be greater than 0. | Supply a positive value within the allowed range. |
Timeout param value must be at least {min_timeout} seconds for {request_type} requests. / Timeout param value cannot exceed {max_timeout} seconds for {request_type} requests. | Templates: bounds depend on browser/curl mode and server configuration. Follow the bounds in your response rather than assuming both modes share one range. |
Invalid js_snippet string. | Direct API calls require base64; official SDKs encode the snippet for you. Avoid double encoding; see JavaScript execution. |
Invalid cookies string. | Use the documented semicolon-separated name=value format; see cookies. |
This domain is not allowed for Free subscription plan. Please, subscribe to a paid plan for accessing it. | A free-plan domain restriction, not a syntax error. Use an allowed target or review plan access; retries/proxy changes do not remove the restriction. |
Worker validation additionally returns the exact full strings Invalid url format. Please check out the documentation: https://docs.scrapingant.com/, Invalid CSS selector. Please check out the documentation: https://docs.scrapingant.com/ and Invalid cookies values. Please check out the documentation: https://docs.scrapingant.com/. Check URL syntax, test the CSS selector in the intended page, or correct cookie values. An invalid selector is different from a valid selector that never appears; the latter does not have a verified unique error message here. See waiting for a selector.
For HTTP 405, confirm the endpoint and method: the v2 scraping routes support GET, POST, PUT, DELETE and PATCH; v1 /general supports GET and POST. Correct the method before retrying. Do not confuse a target's rejection of a forwarded operation with an API 405.
Minimal correction: the fixture at the top can be produced by a dotless host such as url=bad_url, then fixed with url=https://example.com. On v2 send this parameter in the query string, not a JSON configuration body. See first request. This is a source-backed example, not a live capture; no provider request was executed for this guide.
Confirm the fix: check that the same validation message disappears and that the target response has the expected content. Do not retry identical invalid input.
404: This site can’t be reached
Exact detail: This site can’t be reached.
This message covers both site-unavailable and worker-timeout results. It does not establish whether DNS, connectivity or the page-load deadline caused the failure, and it is different from a target 404 in Ant-page-status-code or extended status_code.
Check the target URL and reachability from your own environment first. Remove optional snippets/selectors to isolate a page-load problem, check the API timeout against the returned bounds, and check that your application allows enough time to receive the response. A page that works locally can still be unavailable from another region or proxy. Use browser settings and proxy settings deliberately, one change at a time.
Confirm the fix: inspect the target status and content on a subsequent safe request. Use a small retry budget with increasing delays for an intermittent failure; stop and escalate if the same simple request keeps failing. A Python ScrapingantTimeoutException instead means the SDK timed out communicating with ScrapingAnt; see transport errors.
423: Our browser was detected by target site
Exact detail:
Our browser was detected by target site. Retry the request or try adjusting proxy country, proxy type and browser rendering settings. Our documentation: https://docs.scrapingant.com/ and support email: support@scrapingant.com
The worker reported target-site detection. Inspect which proxy and browser settings you requested. Make one deliberate change using proxy settings or browser rendering, then check the returned content. Residential proxies and rendering can change credit cost; review credits before testing. No setting guarantees access to every target.
Retry decision: a bounded safe retry may succeed after a transient block; repeatedly resending the same blocked request is not a fix. If detection persists, send a sanitized minimal reproduction to support. The JavaScript SDK does not automatically retry HTTP 423.
500: server and extraction errors
Verified detail variants:
Internal server error
Internal server error. Try again later or contact us support@scrapingant.com
AI extraction error. Please try again later or contact us via support@scrapingant.com
Markdown extraction error. Please try again later or contact us via support@scrapingant.com
The first is the unhandled server-exception fallback; the second covers missing/unknown worker results. The extraction messages identify the failing conversion stage on /v2/extract or /v2/markdown; they do not prove the target is unreachable. Check the endpoint and minimize optional parameters. For extraction, check the expected input/output against AI extraction or Markdown.
Confirm the fix: verify the correct output fields and useful content after recovery. For a safe read, use bounded delayed retries; for persistent 500s, contact support with the minimal case. The Python SDK collapses these 500 variants into one exception, so its wording cannot identify the extraction stage.
Retry safely
Fix access and validation failures before retrying. For a temporary failure on an operation that is safe to repeat, use a small maximum attempt count and increasing delays with jitter; stop when the budget is reached. This is application guidance, not an API guarantee of a particular retry interval. Avoid adding an application retry loop on top of a SDK's existing retries without counting the total attempts.
V2 forwards the HTTP method and body to the target. A timeout or 500 does not prove a POST, PUT, PATCH or DELETE had no effect. Before repeating a state-changing operation, confirm the target's outcome or use a target-supported idempotency mechanism. This API reference does not establish a ScrapingAnt idempotency-key contract. A retry that ends in an API error (non-200 status) is not charged; each retry that returns API 200 is charged, whatever the target page contains.
Contact support safely
Use support@scrapingant.com. Include the UTC timestamp, API endpoint/version, SDK/package version if applicable, outer HTTP status, sanitized detail, browser/proxy settings and a minimal reproduction using a public or redacted target. Describe what changed and whether the failure repeats.
The inspected API responses and SDK wrappers do not expose a documented request-ID field/header. Do not invent an X-Request-ID, treat an internal task ID as public, or send a target's Ant-original-header-* identifier as if it were a ScrapingAnt request ID. If your response or account request history actually shows an identifier, copy its exact field name and value privately to support; otherwise say no identifier was available and provide the timestamp.
Never publish API keys, authorization headers, cookies, signed URLs, credentials, private target content or full request/exception dumps. SDK errors and target URLs may contain sensitive values; redact them before sharing, including on public GitHub issues.
Verified against current API source on October 9, 2026, with source-extracted fixtures and mocked SDK tests. This is selected troubleshooting coverage, not a promise that every deployment, gateway or older release emits identical messages.