錯誤碼查詢
31 個正式錯誤碼與 9 個指南補充範例，依失敗類型歸類。處理建議需結合實際版本和 message。
未找到匹配項。保留實際 code 和 message，查看最新響應文檔或聯絡技術支援。
參數與帳戶
| 錯誤碼 / 文件來源 | 排查建議 | 下一步 |
|---|---|---|
PARAMS_ERROR所有版本回應文件 | 檢查缺失欄位、類型和範圍，按 message 修正；V2 的非法逾時值也可能觸發此錯誤。 | 修正配置 |
USER_AGENT_INVALIDv1/v2/v2s回應文件 | 先移除無法解析的 x-cb-ua 或回到預設指紋，核對目前版本的 UA 支援範圍。 | 修正配置 |
APIKEY_INVALID所有版本回應文件 | 確認實際運作環境讀到了有效金鑰，檢查停用或重置狀態，不透過換 IP 解決。 | 停止重試 |
INSUFFICIENT_BALANCE所有版本回應文件 | 查詢 API 積分餘額及到期時間；代理流量為另一項用量，不可互相取代。 | 停止重試 |
HOSTNAME_IS_FORBIDDEN所有版本回應文件 | 核對目標網域與存取許可，保留 message；不要嘗試規避明確的存取限制。 | 人工確認 |
HOSTNAME_IS_NULL所有版本回應文件 | 補齊 x-cb-host，只填入目標主機名稱及必要端口，不含協定、路徑或查詢參數。 | 修正配置 |
HOSTNAME_IS_INVALID按實際返回確認AI 指南補充 | 核對目標主機和端口，保持路徑及查詢參數在 API 請求 URL 中。 | 修正配置 |
PART_ERROR按實際返回確認AI 指南補充 | 核對 x-cb-part 的整數格式及帳戶實際可用範圍，不隨機重複使用其他任務的分割區。 | 修正配置 |
INVALID_SITEKEY按實際返回確認AI 指南補充 | 核對目標的 Turnstile sitekey，並確認請求中同時包含 [cf_token] 佔位符。 | 修正配置 |
代理、網路與憑證
| 錯誤碼 / 文件來源 | 排查建議 | 下一步 |
|---|---|---|
PROXY_ERROR所有版本回應文件 | 檢查代理帳號、協定、連接埠、可用期和流量，區分代理回傳錯誤與目標站回傳錯誤。 | 檢查鏈路 |
PROXY_FORMAT_ERROR所有版本回應文件 | 依請求參數文件核對代理格式，確認所用版本接受該協定；改寫前綴不等於轉換協定。 | 修正配置 |
PROXY_IS_FORBIDDEN所有版本回應文件 | 確認代理地址可被服務使用，改用允許的有效代理；不要重複提交同一被禁止地址。 | 停止重試 |
CONNECTION_ERROR所有版本回應文件 | 區分本機到 API、API 到代理及目標的連接，依據 message 檢查位址和線路。 | 檢查鏈路 |
DNS_ERROR所有版本回應文件 | 先確認失敗的是本地 API 域名、代理域名還是目標域名，分別檢查解析與逾時。 | 檢查鏈路 |
TLS_ERROR所有版本回應文件 | 核對目標和代理協定、系統時間與憑證鏈；不將關閉 TLS 校驗當預設修復。 | 檢查鏈路 |
CERT_ERROR所有版本回應文件 | 檢查憑證鏈、代理程式中間憑證和目標位址；不要把憑證失敗簡單歸類為 IP 問題。 | 檢查鏈路 |
REQUEST_ERROR所有版本回應文件 | 以 message 區分逾時、拒絕和連線中斷，只有安全可重播的臨時失敗才有限重試。 | 有限重試 |
EOF_ERROR所有版本回應文件 | 檢查連線是否提前關閉、代理是否過期、檔案是否完整，不把截斷回應當成功。 | 檢查鏈路 |
RESOLVE_PROXY按實際返回確認AI 指南補充 | 核對代理主機的 DNS 與實際運作環境，記錄解析失敗的 message。 | 檢查鏈路 |
PROXY_CONNECT_ABORTED按實際返回確認AI 指南補充 | 檢查代理認證、有效期限及連線中斷原因，暫時失敗才在預算內重試。 | 檢查鏈路 |
TIMEOUT_ERROR按實際返回確認AI 指南補充 | 區分客戶端等待、API 逾時與目標回應，增加逾時前確認總任務預算。 | 檢查超時 |
SSL_ERROR按實際返回確認AI 指南補充 | 檢查目標、代理程式和用戶端憑證鍊及協議，不預設停用憑證校驗。 | 檢查鏈路 |
驗證挑戰與工作階段
| 錯誤碼 / 文件來源 | 排查建議 | 下一步 |
|---|---|---|
UNSUPPORTED_CAPTCHA所有版本回應文件 | 保留驗證類型與脫敏響應，確認支持邊界後聯繫技術支持，不無限重試。 | 停止重試 |
CLOUDFLARE_PREMIUMv1回應文件 | 文件列為 V1 遇到五秒盾的提示；驗證目標後改用 V2，並準備固定或黏性代理。 | 調整版本 |
CLOUDFLARE_CHALLENGE_TIMEOUTv2回應文件 | 檢查出口穩定性、代理有效期限及兩層逾時；有預算重試，必要時用新工作階段驗證。 | 有限重試 |
DATADOME_CHALLENGE_TIMEOUTv2回應文件 | 檢查固定/黏性代理和挑戰時間預算；持續失敗保留請求 ID，不承諾延時即可成功。 | 有限重試 |
DATADOME_ACCESS_DENIEDv2回應文件 | 核對目標權限、地區和出口信譽；有依據地更換允許的出口，並同步重建工作階段。 | 人工確認 |
CHALLENGE_LOCK_TIMEOUTv2回應文件 | 檢查是否仍有相同工作階段的挑戰在等待；wait-lock 在當前參數文件中已廢棄。 | 先排隊 |
CHALLENGE_LOCK_OCCUPIEDv2回應文件 | 等待相同工作階段的首次挑戰結束，降低並發；獨立任務使用獨立的可用分區。 | 先排隊 |
BYPASS_ERRORv2回應文件 | 先讀 message，重點檢查工作階段期間是否更換代理程式；優先新建工作階段，force 不作為預設配置。 | 檢查工作階段 |
PROXY_NON_STICKYv2回應文件 | 此檢查僅針對穿雲 API代理。改用有效的固定/黏性出口，再建立新的驗證工作階段。 | 修正代理 |
INCAPSULA_ACCESS_DENIED按實際返回確認AI 指南補充 | 依實際拒絕原因核對目標許可、地區和出口；保留證據後確認目標相容性。 | 人工確認 |
目標限制與服務異常
| 錯誤碼 / 文件來源 | 排查建議 | 下一步 |
|---|---|---|
FORBIDDEN所有版本回應文件 | 先檢查目標權限、登入狀態和回應正文；只有明確的挑戰提示才考慮 V2，不把所有 403 當驗證。 | 人工確認 |
ACCESS_DENIED所有版本回應文件 | 核對目標允許的地區、帳號權限和出口信譽，保留拒絕存取的具體證據。 | 人工確認 |
TOO_MANY_REQUESTS所有版本回應文件 | 先降並遵守有效 Retry-After，核對網站與帳號配額，不預設靠換 IP 處理限流。 | 退避等待 |
BAD_GATEWAY所有版本回應文件 | 區分代理、網關和目標來源站，記錄失敗時間與請求 ID；臨時故障可安全地退避重試。 | 有限重試 |
SERVICE_UNAVAILABLE所有版本回應文件 | 檢查目標或網關是否暫時無法使用；依截止時間控制重試，持續失敗再回饋。 | 有限重試 |
SOURCE_SERVER_ERROR所有版本回應文件 | 核對源站錯誤回應，不反覆修改無關參數；保留狀態、時間和請求 ID。 | 有限重試 |
INTERNAL_ERROR所有版本回應文件 | 保留穿雲 API返回的請求 ID、時間及脫敏回應；持續出現時交給技術支援。 | 回饋支持 |
GATEWAY_TIMEOUT按實際返回確認AI 指南補充 | 定位是本地網關、代理或上游等待逾時，再對安全可重播的臨時失敗退避重試。 | 有限重試 |
先保留證據再決定是否重試
01. 有無 HTTP 反應
沒有回應，先查運作環境、DNS、網路、憑證與客戶端逾時，無法編造服務端錯誤碼。
02. 讀取兩層結果
x-cb-status: ok 表示 API 請求處理成功；仍須檢查目標狀態、Content-Type 與業務內容。
03. 保留錯誤字段
API 錯誤 JSON 使用 id、code、message。 SDK 可能拋出異常，需讀取其中的實際反應。
04. 只重試可安全重播的請求
配置錯誤、餘額不足和明確無權限時停止。臨時故障有限退避；有副作用的操作先確認冪等或上次執行結果。
錯誤回應結構
{
"id": "<request-id>",
"code": "PARAMS_ERROR",
"message": "<error-message>"
}欄位值為示意；排查時保留實際回應，不用範例覆寫原始錯誤。
| 觀察到的情況 | 優先判斷 |
|---|---|
| 200 / HTML | 可能是目標內容，也可能是登入頁或驗證頁；先檢查業務欄位。 |
| 403 | 結合回應頭與正文區分挑戰、帳號權限與地區限制。 |
| 429 | 先檢查限流與 Retry-After，降低並發。 |
| 5xx | 區分本地網關、代理、目標源站與 API 傳回的錯誤。 |
版本、代理與工作階段需要一起核對
01. Cookie 與 Part 不混用
Cookie 模式由用戶端儲存並傳送加密驗證 Cookie；Part 模式由服務端託管。 Part 驗證工作階段保留 10 分鐘，期間成功請求可續期，但不會延長代理有效期限。
02. 出口變化後重建工作階段
挑戰期間保持 IP、指紋和代理一致；更換出口後使用新 Part 或 Cookie 工作階段，不在同一分區並發切換代理。
03. 工作階段鎖定先排隊
首次挑戰按工作階段控制並發。鎖定佔用時等待或隔離獨立任務，不預設使用 ignore-lock、force 繞過工作階段約束。
介面版本、代理與逾時核對
| 版本 | 請求與工作階段 | x-cb-timeout |
|---|---|---|
| V1 | 預設自帶動態代理；每次請求無狀態。可依需求配置 x-cb-proxy。 | 預設 30 秒；Go V1 為 5–3600 秒。非法值可能被忽略。 |
| V2 | x-cb-version: 2；必須提供固定或具有時效性的代理，選擇 Cookie 或 Part 模式。 | 預設 15 秒；目前 Python V2 為 5–360 秒，非法值回傳 PARAMS_ERROR。 |
| V2s | x-cb-version: 2s；沿用 V2 代理與工作階段要求，支援串流 HTTP 響應。 | 預設 30 秒；範圍 5–3600 秒。客戶端仍需配置自己的等待預算。 |
容易混淆的請求配置
| 配置 | 應核對的內容 |
|---|---|
| URL 與 x-cb-host | API URL 保留目標路徑和查詢參數；x-cb-host 填目標主機名稱及必要端口，不填協定或路徑。 |
| x-cb-protocol | 目標是 HTTP 時明確設為 http；未設定時預設為 https。 |
| x-cb-proxy | 這是 API 服務存取目標時的出口，不等於給本機 HTTP 用戶端設定代理程式。檢查認證、協定、可用期與出口穩定性。 |
| x-cb-part | 僅 V2 / V2s；文件預設範圍為整數 0–998，實際範圍以服務限制為準。不同任務隔離分區。 |
| x-cb-sitekey | Turnstile 需同時提供 [cf_token] 或 %5Bcf_token%5D 佔位符；JS 質詢不要求填寫 sitekey。 |
| x-cb-fp / x-cb-ua | 核對實際版本的指紋與 UA 行為。目前 Python V2 忽略 x-cb-ua，不隨意拼接瀏覽器版本號。 |
| 重定向與配置選項 | 預設處理重定向；需要檢查 3xx 與 Set-Cookie 時查看 disable-redirect。 wait-lock 已廢棄，ignore-lock 與 force 不作為預設補丁。 |
| 超時與重試 | 有效 x-cb-timeout 優先於 long-timeout。客戶端、SDK、代理和任務截止時間分別核對，避免多層自動重試疊加。 |
代理協定在參數頁與回應頁的說明有差異，需結合所用版本和實際 message 驗證；完整欄位、可用範圍與實作差異以最新請求參數文檔為準。
V2s 是串流回應，不是官方後台任務、輪詢或回呼介面。下載應檢查目標狀態、內容類型與完整性；200 或檔案存在都不足以證明成功。
文件與工具，依問題找到入口
SDK 與 AI 接入
- Python SDK
Session / SessionV2、非同步呼叫與餘額查詢。
- Node.js SDK
cb_version、錯誤辨識與環境變數優先權。
- Go SDK
客戶端、Part / Cookie 與代理功能。
- Vibe Coding 指南
運作環境、錯誤分層、有限重試與 AI 任務邊界。
工具與採集器
- API 轉本地代理工具
檢查監聽位址、預設金鑰及 x-cb-proxy。
- Nginx 轉送配置
服務端保管金鑰，並核對 Host、SNI 與存取範圍。
- 採集器配置
複用本地代理工具；不要照抄截圖中的 x-cb-host。
計費、試用與能力邊界
- 積分消耗
請求成功與挑戰成功分別計費。
- 領取試用
註冊後按文件聯絡客戶服務。
- 指紋瀏覽器與自動化邊界
文件明確不支援在指紋瀏覽器、Selenium、Puppeteer 直接使用。
- WebSocket 邊界
目前文件明確不支援 ws / wss。
積分、餘額與 SDK 配置差異
先區分 API 積分和代理流量
官方文件說明：請求成功消耗 1 積分，V2 每次驗證挑戰成功額外消耗 2 積分；多階段驗證分別計費。挑戰成功後若後續回應錯誤，已扣挑戰積分不返還，但失敗回應不扣請求積分。 SDK 自動跟隨重定向的回應也會消耗積分。
餘額接口為 POST https://console.cloudbypass.com/api/v1/balance，使用 JSON 字段 apikey、email、type。points 查詢積分與到期時間，res / dat 查詢住宅 / 機房流量，單位為位元組。舊 GET 查詢已廢棄，不把憑證放在 URL 中。
SDK 的環境變數約定不同：Python / Go 文件使用 CB_APIKEY、CB_PROXY；Node.js 優先讀取 CLOUDBYPASS_APIKEY、CLOUDBYPASS_PROXY，為空時再讀取 CB_*。 AI 指南中的變數不會自動出現在每個 SDK 或遠端 MCP 環境中。
本機代理工具及 Nginx 皆為轉送存取方式；金鑰保存在可信任運作環境，監聽範圍及存取權限需受控。文件明確不支援直接在指紋瀏覽器、Selenium / Puppeteer 中使用，也不支援 WebSocket 的 ws / wss，不將 HTTP 串流反應混同於這些能力。
常見問題與回饋證據
HTTP 200 就表示任務成功了嗎？
不是。先檢查 x-cb-status，再檢查目標 HTTP 狀態、Content-Type 和業務欄位。 x-cb-status: ok 表示穿雲 API請求處理成功，不代表登入、下單或檔案保存等業務一定完成。
沒有收到回應時，應該查哪個錯誤碼？
沒有 HTTP 反應時，不能編造穿雲 API服務端錯誤碼。先檢查本地依賴、運作環境、DNS、網路、憑證和客戶端逾時；收到回應後再讀取實際 id、code、message。
所有 403 都需要切換 V2 嗎？
不是。 403 也可能來自帳號無權限、地區限製或目標業務規則。 V1 明確提示 CLOUDFLARE_PREMIUM 或傳回訊息要求 V2 時，再設定 V2 與穩定代理；普通權限錯誤不會因升級版本而自動消失。
DataDome 需要新增專用請求頭嗎？
快速開始文件說明由 V2 自動識別 DataDome 挑戰，無需額外 DataDome 專用頭。仍須配置固定或黏性 x-cb-proxy，並使用相符的 Cookie 或 Part 工作階段；目標相容性需實際驗證。
填寫 sitekey 後為什麼沒有完成 Turnstile？
x-cb-sitekey 也需要配合 URL、請求頭或請求體中的 [cf_token] 或其 URL 編碼佔位符。 穿雲 API取代佔位符後轉送目標請求，並非把裸 Token 作為通用回傳值直接交給客戶端。
為什麼請求失敗仍然消耗積分？
文件區分請求積分和挑戰積分：請求成功消耗 1 積分，V2 每次驗證挑戰成功額外消耗 2 點。挑戰成功後若後續回應錯誤，已扣的挑戰積分不返還，但此失敗回應不扣請求積分；多階段驗證依階段計算。
V2s 等於後台非同步任務介面嗎？
不是。 V2s 是串流 HTTP 回應，不自動提供官方後台任務、輪詢或回調服務。客戶端非同步呼叫也不等於服務端建立任務，下載仍需校驗實際內容與完整性。
回饋問題時需要傳送 API Key 嗎？
不需要。提供時間與時區、請求 ID、脫敏目標、版本、code/message、代理地區與類型及嘗試記錄即可。不要傳送 API Key、代理密碼、登入 Cookie、完整請求體或帶有 Token 的查詢參數。
聯繫支援時保留這些訊息
- 發生時間與時區、請求 ID
- 減敏目標、API 版本、HTTP 狀態
- x-cb-status、原始 code 與去敏感化 message
- 代理類型、地區、有效期限與工作階段方式
- 已嘗試的步驟與最終結果
不附帶金鑰、代理密碼、登入 Cookie 或敏感查詢參數。沒有請求 ID 時如實說明，不產生一個替代值。