Find the cause of a failed request
Check the HTTP status, error code and response details, then review your API version, proxy and session settings before continuing.
Error code lookup
31 official error codes and 9 guidance supplement examples, organized by failure type. The processing suggestions need to be combined with the actual version and message.
No match found. Keep the actual code and message,View the latest response documentationorContact technical support。
Parameters and account
| Error code/Document source | Troubleshooting suggestions | Next step |
|---|---|---|
PARAMS_ERRORAll versionsresponse document | Check for missing fields, types and ranges, fix by message; illegal timeout values in V2 may also trigger this error. | Fix configuration |
USER_AGENT_INVALIDv1/v2/v2sresponse document | First remove the unresolved x-cb-ua or return to the default fingerprint and check the current version of UA support range. | Fix configuration |
APIKEY_INVALIDAll versionsresponse document | Confirm that the actual operating environment has read the valid key, check the disabled or reset status, and do not solve it by changing the IP. | Stop retrying |
INSUFFICIENT_BALANCEAll versionsresponse document | Query the API credits balance and expiration time; proxy traffic is another usage and cannot be replaced by each other. | Stop retrying |
HOSTNAME_IS_FORBIDDENAll versionsresponse document | Check the target domain name and access permissions, and keep the message; do not try to circumvent explicit access restrictions. | Manual confirmation |
HOSTNAME_IS_NULLAll versionsresponse document | Complete x-cb-host, only fill in the target host name and necessary ports, without protocol, path or query parameters. | Fix configuration |
HOSTNAME_IS_INVALIDConfirm by actual returnAI Guide Supplement | Check the target host and port, keeping the path and query parameters in the API request URL. | Fix configuration |
PART_ERRORConfirm by actual returnAI Guide Supplement | Check the integer format of x-cb-part and the actual available range of the account, and do not randomly reuse partitions for other tasks. | Fix configuration |
INVALID_SITEKEYConfirm by actual returnAI Guide Supplement | Check the target's Turnstile sitekey and confirm that the request also contains the [cf_token] placeholder. | Fix configuration |
Proxy, network and TLS
| Error code/Document source | Troubleshooting suggestions | Next step |
|---|---|---|
PROXY_ERRORAll versionsresponse document | Check the proxy account, protocol, port, availability period and traffic, and distinguish errors returned by the proxy from errors returned by the target site. | Check link |
PROXY_FORMAT_ERRORAll versionsresponse document | Check the proxy format according to the request parameter document and confirm that the version used accepts the protocol; rewriting the prefix does not mean converting the protocol. | Fix configuration |
PROXY_IS_FORBIDDENAll versionsresponse document | Confirm that the proxy address can be used by the service and use a valid, allowed proxy instead; do not submit the same banned address repeatedly. | Stop retrying |
CONNECTION_ERRORAll versionsresponse document | Distinguish the connection from the local machine to API, API to the proxy and the target, and check the address and line based on the message. | Check link |
DNS_ERRORAll versionsresponse document | First confirm whether the failed domain name is the local API domain name, proxy domain name or target domain name, and check the resolution and timeout respectively. | Check link |
TLS_ERRORAll versionsresponse document | Check target and proxy protocols, system time and certificate chain; fix not turning off TLS verification as default. | Check link |
CERT_ERRORAll versionsresponse document | Check the certificate chain, proxy intermediate certificates, and destination addresses; do not simply attribute certificate failures to IP issues. | Check link |
REQUEST_ERRORAll versionsresponse document | Timeouts, rejections, and connection interruptions are distinguished by message, and only safe replayable temporary failures have limited retries. | Limited retries |
EOF_ERRORAll versionsresponse document | Check whether the connection is closed prematurely, whether the proxy has expired, whether the file is complete, and do not treat truncated responses as success. | Check link |
RESOLVE_PROXYConfirm by actual returnAI Guide Supplement | Check the DNS of the proxy host with the actual operating environment, and record the message of resolution failure. | Check link |
PROXY_CONNECT_ABORTEDConfirm by actual returnAI Guide Supplement | Check the proxy authentication, validity period and connection interruption reasons, and only try again within the budget after temporary failure. | Check link |
TIMEOUT_ERRORConfirm by actual returnAI Guide Supplement | Distinguish between client wait, API timeout and target response, and confirm the total task budget before increasing the timeout. | Check timeout |
SSL_ERRORConfirm by actual returnAI Guide Supplement | Check target, proxy and client certificate chains and protocols and do not disable certificate verification by default. | Check link |
Challenges and sessions
| Error code/Document source | Troubleshooting suggestions | Next step |
|---|---|---|
UNSUPPORTED_CAPTCHAAll versionsresponse document | Keep the verification type and desensitization response, contact technical support after confirming the support boundary, and do not retry infinitely. | Stop retrying |
CLOUDFLARE_PREMIUMv1response document | Documentation lists tips for V1 encountering five-second shields; switch to V2 after verifying targets, and prepare for fixed or sticky proxies. | Adjust version |
CLOUDFLARE_CHALLENGE_TIMEOUTv2response document | Check egress stability, proxy validity, and two-tier timeouts; retry with budget and verify with new sessions if necessary. | Limited retries |
DATADOME_CHALLENGE_TIMEOUTv2response document | Check for fixed/sticky proxies and challenge time budgets; persistent failures retain request IDs and succeed without committing to delays. | Limited retries |
DATADOME_ACCESS_DENIEDv2response document | Check the target permissions, region and export reputation; change the allowed exports based on the basis, and re-establish the session simultaneously. | Manual confirmation |
CHALLENGE_LOCK_TIMEOUTv2response document | Check if there are still challenges waiting for the same session; wait-lock is deprecated in the current parameter documentation. | Queue first |
CHALLENGE_LOCK_OCCUPIEDv2response document | Wait for the first challenge of the same session to end to reduce concurrency; independent tasks use independent available partitions. | Queue first |
BYPASS_ERRORv2response document | Read the message first, and focus on checking whether the proxy is changed during the session; create a new session first, and force is not used as the default configuration. | Check session |
PROXY_NON_STICKYv2response document | This check is only for the Scrapingbypass API proxy. Use a valid pinned/sticky exit instead and create a new authentication session. | Fix proxy |
INCAPSULA_ACCESS_DENIEDConfirm by actual returnAI Guide Supplement | Verify target licenses, regions, and exports against actual denial reasons; retain evidence to confirm target compatibility. | Manual confirmation |
Target restrictions and service errors
| Error code/Document source | Troubleshooting suggestions | Next step |
|---|---|---|
FORBIDDENAll versionsresponse document | Check target permissions, login status, and response body first; only consider V2 if there is a clear challenge prompt, and do not treat all 403s as validation. | Manual confirmation |
ACCESS_DENIEDAll versionsresponse document | Check the target's allowed regions, account permissions, and export reputation, and retain specific evidence of access denial. | Manual confirmation |
TOO_MANY_REQUESTSAll versionsresponse document | Reduce concurrency first and comply with effective Retry-After, check site and account quotas, and do not rely on changing IP to handle current limiting by default. | Back off and wait |
BAD_GATEWAYAll versionsresponse document | Distinguish between proxies, gateways, and target origins, and record failure time and request ID; temporary failures can be safely backed off and retried. | Limited retries |
SERVICE_UNAVAILABLEAll versionsresponse document | Check whether the target or gateway is temporarily unavailable; control retry according to the deadline, and feedback after continuous failure. | Limited retries |
SOURCE_SERVER_ERRORAll versionsresponse document | Check the origin site error response and do not repeatedly modify irrelevant parameters; retain the status, time and request ID. | Limited retries |
INTERNAL_ERRORAll versionsresponse document | Keep the request ID, time and desensitization response returned by Scrapingbypass API; if it continues to occur, hand it over to technical support. | feedback support |
GATEWAY_TIMEOUTConfirm by actual returnAI Guide Supplement | Locate whether it is the local gateway, proxy or upstream and wait for the timeout, and then try again for safe and replayable temporary failures. | Limited retries |
Source:response data、AI access fault diagnosis. Unknown errors retain their original values and are not uniformly classified as "Change IP".
Keep the evidence firstDecide whether to try again
01. Is there a HTTP response?
If there is no response, first check the operating environment, DNS, network, certificate and client timeout. Do not make up server error codes.
02. Read two levels of results
x-cb-status: ok means that the API request is processed successfully; the target status, Content-Type and business content must still be checked.
03. Keep error fields
API Error JSON uses id, code, message. SDK may throw an exception, the actual response needs to be read.
04. Only retry requests that are safe to replay
Stops on configuration errors, insufficient balance, and explicit no permissions. Limited backoff for temporary failures; operations with side effects first confirm idempotence or the last execution result.
error response structure
{
"id": "<request-id>",
"code": "PARAMS_ERROR",
"message": "<error-message>"
}Field values are for reference; keep the actual response when troubleshooting, and do not use examples to cover the original errors.
| Observed situation | Prioritize judgment |
|---|---|
| 200/HTML | It could be target content, it could be a login page or a verification page; check the business fields first. |
| 403 | Combine response headers and body to distinguish challenges, account permissions, and regional restrictions. |
| 429 | Check current limiting and Retry-After first to reduce concurrency. |
| 5xx | Differentiate between local gateway, proxy, target origin and errors returned by API. |
Versions, proxies and SessionsNeed to check together
01. Cookies and Parts do not mix
Cookie mode is saved by the client and sends encrypted verification cookies; Part mode is hosted by the server. Part verification sessions are retained for 10 minutes, during which successful requests can be renewed, but the proxy validity period will not be extended.
02. Rebuilding session after export changes
Keep the IP, fingerprint, and proxy consistent during the challenge; use a new Part or Cookie session after changing the exit, and do not switch proxies concurrently in the same partition.
03. Session locks are queued first
The first challenge controls concurrency on a per-session basis. Wait for or isolate independent tasks when the lock is occupied, and ignore-lock and force are not used by default to bypass session constraints.
API version, proxy and timeout check
| version | Requests and sessions | x-cb-timeout |
|---|---|---|
| V1 | It comes with a dynamic proxy by default; each request is stateless. x-cb-proxy can be configured as required. | Default 30 seconds; 5–3600 seconds for Go V1. Illegal values may be ignored. |
| V2 | x-cb-version: 2; Fixed or time-sensitive proxy must be provided, select Cookie or Part mode. | The default is 15 seconds; the current Python V2 is 5–360 seconds, and illegal values return PARAMS_ERROR. |
| V2s | x-cb-version: 2s; follows V2 proxy and session requirements, supports streaming HTTP response. | Default 30 seconds; range 5–3600 seconds. Clients still need to configure their own wait budget. |
Confusing request configuration
| Configuration | Things to check |
|---|---|
| URL and x-cb-host | API URL retains the target path and query parameters; x-cb-host fills in the target host name and necessary ports, but does not fill in the protocol or path. |
| x-cb-protocol | Explicitly set to http when target is HTTP; defaults to https if not set. |
| x-cb-proxy | This is the exit when the API service accesses the target, and is not equivalent to configuring a proxy for the local HTTP client. Check certifications, agreements, availability and export stability. |
| x-cb-part | V2/V2s only; document default range is integer 0–998, actual range is subject to service limitations. Isolate partitions for different tasks. |
| x-cb-sitekey | Turnstile needs to be provided with [cf_token] or %5Bcf_token%5D placeholder; JS query does not require filling in sitekey. |
| x-cb-fp / x-cb-ua | Check the fingerprint of the actual version against the UA behavior. Currently Python V2 ignores x-cb-ua and does not randomly splice browser version numbers. |
| Redirects and configuration options | Redirects are handled by default; see disable-redirect if you need to check for 3xx and Set-Cookie. wait-lock is deprecated, ignore-lock and force are not used as default patches. |
| Timeouts and retries | Valid x-cb-timeout takes precedence over long-timeout. The client, SDK, proxy and task deadlines are checked separately to avoid the superposition of multiple layers of automatic retries. |
There are differences in the descriptions of the proxy protocol on the parameter page and the response page, which need to be verified based on the version used and the actual message; the complete fields, available ranges and implementation differences are as followsLatest request parameter documentationshall prevail.
V2s is a streaming response, not an official background task, polling or callback interface. Downloads should check destination status, content type, and integrity; neither 200 nor the existence of the file is sufficient to prove success.
Documents and tools, find the entrance by question
Getting Started and Responsive
- quick start
V1/V2/V2s, challenge types and two session modes.
- Request parameters
Destination path, request headers, fingerprints, timeouts and configuration options.
- response data
x-cb-status, error JSON and official error code table.
- Check account balance
POST + JSON Query credits or proxy traffic.
SDK and AI access
- Python SDK
Session/SessionV2, asynchronous call and balance query.
- Node.js SDK
cb_version, error identification and environment variable priority.
- Go SDK
Client, Part/Cookie and proxy functions.
- Vibe Coding Guide
Runtime environment, error stratification, limited retries, and AI task boundaries.
Tools and collectors
- API to local proxy tool
Check the listening address, default key, and x-cb-proxy.
- Nginx forwarding configuration
The server keeps the key and checks the Host, SNI and access scope.
- Collector configuration
Reuse local proxy tools; don't copy x-cb-host in the screenshot.
Billing, Trial and Capability Boundaries
- credits consumption
Successful requests and successful challenges are billed separately.
- Get a trial
After registration, contact customer service according to the document.
- Fingerprint browsers and automated borders
The document clearly does not support direct use in fingerprint browsers, Selenium, and Puppeteer.
- WebSocket Boundary
The current documentation explicitly does not support ws/wss.
credits, balance and SDK configuration differences
First distinguish between API credits and proxy traffic
Official document description: A successful request consumes 1 point, and each successful V2 verification challenge consumes an additional 2 credits; multi-stage verification is billed separately. If the subsequent response after a successful challenge is incorrect, the challenge credits already deducted will not be returned, but the request credits will not be deducted for a failed response. SDK Automatically following redirect responses also consumes credits.
The balance interface is POST https://console.cloudbypass.com/api/v1/balance, using the JSON field apikey、email、type。points Check credits and expiration time,res / dat Query residential/computer room traffic, unit is bytes. The old GET query is deprecated and does not put credentials in the URL.
SDK has different environment variable conventions: Python / Go documentation usage CB_APIKEY、CB_PROXY;Node.js priority reading CLOUDBYPASS_APIKEY、CLOUDBYPASS_PROXY, read again when empty CB_*. Variables in the AI guide do not automatically appear in every SDK or remote MCP environment.
Both the local proxy tool and Nginx are forwarding access methods; the key is stored in a trusted operating environment, and the monitoring scope and access permissions need to be controlled. The documentation explicitly does not support use directly in fingerprint browsers, Selenium / Puppeteer, nor does it support ws / wss for WebSocket, and does not confuse HTTP streaming responses with these capabilities.
Frequently Asked Questions and Feedback Evidence
HTTP 200 means the mission is successful?
No. Check x-cb-status first, then check the target HTTP status, Content-Type and business fields. x-cb-status: ok means that the Scrapingbypass API request is processed successfully, but it does not mean that login, order placing or file saving and other services must be completed.
When no response is received, which error code should be checked?
When there is no HTTP response, the Scrapingbypass API server error code cannot be fabricated. First check the local dependencies, operating environment, DNS, network, certificate and client timeout; after receiving the response, read the actual id, code and message.
Do all 403s need to be switched to V2?
No. 403 may also come from account no permissions, region restrictions, or target task rules. When V1 clearly prompts CLOUDFLARE_PREMIUM or returns information requesting V2, configure V2 and the stable proxy; ordinary permission errors will not disappear automatically due to upgraded versions.
DataDome Do I need to add a special request header?
The Quick Start documentation states that the DataDome challenge is automatically recognized by V2 without the need for an additional DataDome dedicated header. Fixed or sticky x-cb-proxy must still be configured and use matching cookie or part sessions; target compatibility requires actual verification.
Why is Turnstile not completed after filling in the sitekey?
x-cb-sitekey also needs to be matched by [cf_token] or its URL-encoded placeholder in the URL, request header, or request body. Scrapingbypass API replaces the placeholder and forwards the target request, instead of giving the naked Token directly to the client as a general return value.
Why do failed requests still consume credits?
The documentation distinguishes between request credits and challenge credits: a successful request consumes 1 point, and V2 consumes an additional 2 credits for each successful verification challenge. If the subsequent response is incorrect after the challenge is successful, the deducted challenge credits will not be returned, but the request credits will not be deducted for the failed response; multi-stage verification is calculated by stage.
Is V2s equal to the background asynchronous task interface?
No. V2s are streaming HTTP responses and do not automatically provide official background tasks, polling, or callback services. Asynchronous calls from the client do not mean creating tasks on the server, and downloads still need to verify the actual content and integrity.
Do I need to send API Key when reporting a problem?
No need. Just provide the time and time zone, request ID, desensitization target, version, code/message, proxy region and type, and attempt record. Do not send API Key, proxy password, login cookie, full request body, or query parameters with Token.
Keep this information when contacting support
- Occurrence time and time zone, request ID
- Desensitization target, API version, HTTP status
- x-cb-status, original code and desensitized message
- proxy type, region, validity period and session mode
- Steps Tried and Final Result
Does not come with keys, proxy passwords, login cookies, or sensitive query parameters. If there is no request ID, specify it truthfully and do not generate a substitute value.