Bankworks

Errors

Failures are JSON with "ok": false and a message written for a human. The status code tells you whether retrying can possibly help.

JSON
{"ok": false, "error": "Human-readable message", "code": "machine_readable"}

Status codes

CodeCauseRetry?
400Malformed request: bad URL, too many URLs, a value out of rangeNo — fix the request
401Missing, invalid, expired or revoked keyNo
403Valid key, missing scopeNo
404No such resource — or it is not yoursNo
409Wrong state, e.g. HTML requested for a task that is not DONEAfter the state changes
402Not enough plan allowance or balance for what you askedAfter adding funds or choosing a plan
429Rate limit exceededYes, after Retry-After
503No capacity, or a circuit is open for that hostYes, after Retry-After
500A defect on our sideOnce, then tell us
404 is deliberate for resources you do not own. A 403 would confirm that the identifier exists. The API will not tell you about another account's data, including whether it is there.

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.

errorCodeWhat happenedWhat to do
CAPTCHA_REQUIREDA supported CAPTCHA challenge was detected on a Regular requestIf you are authorized to access the page, submit it with "package": "advance". Not billed
CAPTCHA_UNSOLVEDAdvance could not handle the CAPTCHA challenge encountered during scrapingThe request was not billed; use an access method permitted by the site
BOT_PROTECTEDThe website is protected by DataDome, which refuses automated access from our networkNot retried, in either package. Not billed
BLOCKEDThe site served a block or challenge pageNothing to change on your side: the site may refuse automated access
TEMPORARILY_BLOCKEDThe site is refusing our network for a whileRetry later
NAVIGATIONThe page navigated while being readRaise postLoadDelayMs to 3000–5000
TIMEOUTThe page never finished loadingRaise navigationTimeoutMs, or set blockAssets true
EXPECTED_TEXT_MISSINGThe page loaded without your expectedTextThe page loaded without your text: billed once, and its HTML is downloadable. Check the string, or the page
EMPTY_PAGEThe page returned almost no contentCheck the URL in a browser
REDIRECT_LOOPThe site redirected too many timesCheck the URL; some sites loop for automated visitors
DNS_ERRORThe hostname does not resolveCheck the URL
UNREACHABLEThe site could not be reached (a net::ERR_… code is included)Check the URL; retry later
NO_CAPACITYNo crawler is available for that site right nowAsk us to add capacity for it
TOO_LARGEThe page is bigger than the size limitAsk us about the limit
FAILEDAnything elseRetry 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

Text
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.