错误码查询
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响应文档 | 此检查仅针对穿云代理。改用有效的固定/粘性出口，再创建新的验证会话。 | 修正代理 |
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所有版本响应文档 | 保留穿云返回的请求 ID、时间及脱敏响应；持续出现时交给技术支持。 | 反馈支持 |
GATEWAY_TIMEOUT按实际返回确认AI 指南补充 | 定位是本地网关、代理还是上游等待超时，再对安全可重放的临时失败退避重试。 | 有限重试 |
先保留证据再决定是否重试
01. 有无 HTTP 响应
没有响应，先查运行环境、DNS、网络、证书与客户端超时，不能编造服务端错误码。
02. 读取两层结果
x-cb-status: ok 表示 API 请求处理成功；仍须检查目标状态、Content-Type 与业务内容。
03. 保留错误字段
API 错误 JSON 使用 id、code、message。SDK 可能抛出异常，需读取其中的实际响应。
04. 只重试可安全重放的请求
配置错误、余额不足和明确无权限时停止。临时故障有限退避；有副作用的操作先确认幂等或上次执行结果。
错误响应结构
{
"id": "<实际请求 ID>",
"code": "PARAMS_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 表示穿云请求处理成功，不代表登录、下单或文件保存等业务一定完成。
没有收到响应时，应该查哪个错误码？
没有 HTTP 响应时，不能编造穿云服务端错误码。先检查本地依赖、运行环境、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 编码占位符。穿云替换占位符后转发目标请求，并非把裸 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 时如实说明，不生成一个替代值。