This page moved to https://docs.fastcrw.com/error-codes.
Errors and Warnings
Response semantics
success: truemeans the pipeline produced usable page content.success: falsemeans the request failed -- either an engine error or the target returned an error status (4xx/5xx) with minimal content.erroris present whensuccess: false. It describes what went wrong.warningflags degraded target outcomes (problematic status codes, a partial render) whensuccess: true, meaning content was produced but may be incomplete. An anti-bot wall is not one of these: it is alwayssuccess: falsewitherrorCode: "anti_bot". On the cloud, whenmode: "auto"can get past the wall, theerrormessage ends with a pointer to it (Auto and max mode).metadata.statusCodeis the target site's HTTP status.datamay still be present whensuccess: falseif partial content was extracted.
The important distinction is that there are two layers of status:
- the HTTP status returned by CRW,
- and the target site's own status exposed through
metadata.statusCode.
You need both to debug real scraping failures.
HTTP status codes returned by the API
| Status | Meaning |
|---|---|
| 200 | Success |
| 400 | Invalid request parameters (bad URL, invalid JSON body, invalid selector) |
| 401 | Invalid or missing API key |
| 404 | Endpoint not found |
| 422 | Validation failed (unknown format, invalid schema, extraction error), or the origin returned a body that is not a page (unsupported_content_type) or is over the size cap (response_too_large), or a browser action could not be carried out (action_failed) |
| 402 | Cloud only: the credit balance cannot cover the request (errorCode: "insufficient_credits"), or a managed-LLM feature was requested on the FREE plan (errorCode: "llm_not_available") |
| 429 | Request-rate or concurrency limit exceeded (on the legacy /v2 surface, also an exhausted credit balance) |
| 502 | Engine internal error |
| 503 | Server at capacity |
| 504 | Request timed out |
How To Read Common Cases
| Situation | What it usually means | What to do next |
|---|---|---|
HTTP 200 with warning |
The request succeeded, but the target result is degraded | Inspect warning and metadata.statusCode |
HTTP 400 |
Your request body is invalid | Fix fields, selectors, or schema |
HTTP 422 |
The request shape is valid JSON but semantically invalid | Check format names, schema, or extraction config |
unsupported_content_type |
The origin served an office document, image or archive rather than a page | Fetch the file yourself, or point the request at a PDF or an HTML page |
response_too_large |
The origin's body is over the 50 MB response cap (a very large PDF, most often) | Do not retry; the same document is too large every time. Fetch the file yourself |
action_failed |
A browser action could not be carried out: its element never appeared, or the page threw. The message names the step | Fix the selector, mark the step optional: true, or add a wait before it. Not billed |
HTTP 402 |
Out of credits (insufficient_credits) or a paid-plan feature on the FREE plan (llm_not_available) |
Do not retry; top up, upgrade or enable auto-recharge |
HTTP 429 |
Request-rate or concurrency limit hit | Back off and honor Retry-After |
HTTP 502 / 504 |
Upstream or timeout issue | Retry with backoff |
Common engine errors
| Error | When it happens |
|---|---|
| Invalid URL | URL is malformed or targets a blocked address |
| Invalid selector | CSS selector or XPath expression cannot be parsed |
| Renderer timeout | JS rendering exceeded the page timeout |
| Navigation failed | CDP browser could not load the page |
| Response too large | The origin's body exceeded the 50 MB response cap (response_too_large, HTTP 422) |
| Invalid JSON schema | Schema provided for extraction is malformed |
| Extraction failure | LLM extraction failed (no LLM configured, or LLM returned an error) |
summary format requires LLM config |
formats: ["summary"] sent without a server-side [extraction.llm] block and without per-request llmApiKey |
| Key header required | Server is in key-required mode (require_byok_header) and the request lacks both the header and llmApiKey |
| No JS renderer available | renderJs: true but no CDP browser is configured |
Cloud-only error codes
The managed cloud adds these errorCode values on top of the engine's own. Self-hosted instances have no billing layer and never send them.
errorCode |
HTTP | When it happens |
|---|---|---|
insufficient_credits |
402 | The credit balance cannot cover the request: FREE lifetime credits used up, or a paid plan's included and top-up credits used up. Carries the X-FASTCRW-Credits-Available, X-FASTCRW-Included-Remaining, X-FASTCRW-Purchased-Remaining and X-FASTCRW-Upgrade-Url headers, plus X-FASTCRW-Stop-Reason when an enabled auto-recharge could not run. No Retry-After. Not sent on the legacy /v2 surface, which answers 429 instead. |
invalid_mode |
400 | mode is not standard, auto or max; maxCredits is out of range, sent without auto or max, at or below the page's base price, or spelled max_credits; or mode: "max" came with renderJs: false, a pinned renderer, a screenshot or a timeout under 35000 ms. |
mode_with_llm_format |
400 | mode: "auto" or "max" combined with summary, json or the change-tracking judge. |
mode_unavailable |
403 | Auto and max mode are switched off right now. Nothing is charged; retry later or use standard mode. |
plan_required |
403 | Auto and max mode need the Standard plan or higher. |
insufficient_credits_for_mode |
402 | The balance cannot cover the hold of an auto or max page (its maxCredits, or the per-page limit). Plain scrapes still work. |
mode_concurrency |
429 | The account already has 4 auto or max pages in flight. Retry when one finishes. |
mode_failure_budget |
429 | Too many auto or max pages failed today. Failed pages are not charged; the limit resets at 00:00 UTC. |
llm_not_available |
402 | A managed-LLM feature (search answer / summarizeResults, /v1/extract) was requested on the FREE plan. The /v1/crawl LLM formats gate sends the same code with HTTP 403. |
Data source calls (/v1/data/*, crw_find_data, crw_get_data, and the SDKs' findData / getData) send their own codes, such as client_execution_required, unknown_data_source, upstream_error, upstream_timeout, upstream_rate_limited, invalid_response and result_too_large. The SDKs pass them on as errorCode (error_code in Python). The full list, with what to do about each, is in the Errors section of Data Sources.
Common warnings
| Warning | When it appears |
|---|---|
Target returned 403 Forbidden |
Target site blocked the request |
Target returned 429 Too Many Requests |
Target site rate limited the request |
Blocked by anti-bot protection |
Page contains Cloudflare/captcha markers |
JS rendering was requested but no renderer is available |
Fallback to HTTP-only fetch |
content truncated to N bytes before summarization |
Scraped content exceeded maxContentChars (or [extraction.llm].max_html_bytes); the head of the page was summarized |
summary failed: <reason> |
A per-result summary in /v1/search failed (e.g. provider 429). Other results are still returned |
answer synthesis failed: <reason> |
The answer call in /v1/search failed. answer is null but summaries and results are still returned |
N of M per-result summaries failed |
Some but not all per-result summaries failed in /v1/search |
Retry Guidance
Retrying helps only for some classes of failure:
- retry
429,502, and504with backoff, honoringRetry-Afterwhen present, - never retry a
402: out of credits (insufficient_credits) and the FREE-plan LLM gate (llm_not_available) clear only when the account changes; the same goes for a legacy/v2429that carriesX-FASTCRW-Credits-Available, - do not blindly retry
400or422, - and treat repeated warnings from the same domain as a target compatibility problem, not a random transient issue.
If a page is repeatedly blocked by anti-bot protection, longer retry loops usually make the situation worse rather than better.