Errors
Failures are JSON with "ok": false and a message written for
a human. The status code tells you whether retrying can possibly help.
{"ok": false, "error": "Human-readable message", "code": "machine_readable"}
Status codes
| Code | Cause | Retry? |
|---|---|---|
| 400 | Malformed request: bad URL, too many URLs, a value out of range | No — fix the request |
| 401 | Missing, invalid, expired or revoked key | No |
| 403 | Valid key, missing scope | No |
| 404 | No such resource — or it is not yours | No |
| 409 | Wrong state, e.g. HTML requested for a task that is not DONE | After the state changes |
| 402 | Not enough plan allowance or balance for what you asked | After adding funds or choosing a plan |
| 429 | Rate limit exceeded | Yes, after Retry-After |
| 503 | No capacity, or a circuit is open for that host | Yes, after Retry-After |
| 500 | A defect on our side | Once, then tell us |
Task failures are not HTTP failures
A job can return 201 and still contain tasks that end
FAILED. The HTTP code describes your request; the task status
describes the page. Always read failedTasks.
Task error codes
A failed task has a short error sentence and an
errorCode your program can switch on. The codes are stable;
the sentences may be reworded.
| errorCode | What happened | What to do |
|---|---|---|
CAPTCHA_REQUIRED | A supported CAPTCHA challenge was detected on a Regular request | If you are authorized to access the page, submit it with "package": "advance". Not billed |
CAPTCHA_UNSOLVED | Advance could not handle the CAPTCHA challenge encountered during scraping | The request was not billed; use an access method permitted by the site |
BOT_PROTECTED | The website is protected by DataDome, which refuses automated access from our network | Not retried, in either package. Not billed |
BLOCKED | The site served a block or challenge page | Nothing to change on your side: the site may refuse automated access |
TEMPORARILY_BLOCKED | The site is refusing our network for a while | Retry later |
NAVIGATION | The page navigated while being read | Raise postLoadDelayMs to 3000–5000 |
TIMEOUT | The page never finished loading | Raise navigationTimeoutMs, or set blockAssets true |
EXPECTED_TEXT_MISSING | The page loaded without your expectedText | The page loaded without your text: billed once, and its HTML is downloadable. Check the string, or the page |
EMPTY_PAGE | The page returned almost no content | Check the URL in a browser |
REDIRECT_LOOP | The site redirected too many times | Check the URL; some sites loop for automated visitors |
DNS_ERROR | The hostname does not resolve | Check the URL |
UNREACHABLE | The site could not be reached (a net::ERR_… code is included) | Check the URL; retry later |
NO_CAPACITY | No crawler is available for that site right now | Ask us to add capacity for it |
TOO_LARGE | The page is bigger than the size limit | Ask us about the limit |
FAILED | Anything else | Retry once; if it persists, tell us the task id |
Blocked pages fail on purpose
A challenge page usually arrives as HTTP 200 with a body
that contains no content. Storing that as a success would hand you a file
that looks fine and is worthless, so we detect the block, quarantine the
exit IP and retry elsewhere. If every attempt is blocked the task ends
FAILED — which is the honest answer.
The strongest guard you control is expectedText: name a
string that only the real page contains, and anything else is rejected
before it reaches you.
A retry policy that works
429, 503 → wait Retry-After, then retry
500 → retry once after a few seconds
400,401,403,404,409 → do not retry; the next attempt fails identically
Per-task retries are already handled server-side, including rotating to a different exit IP. You do not need to resubmit a job because some tasks failed — check whether the attempts were exhausted first.
A client that waits out 429 and 503 correctly, in Python, Node.js and cURL, is on the rate limits page.