常见错误码与处理建议
统一维护公开 API 的 HTTP 状态、数字业务码、响应字段及恢复方式。
错误码用于确定失败阶段,不能单独证明网关、出口或客户端存在故障。排查时同时保留请求时间和请求 ID。
响应状态与字段
公开静态 API 成功统一为 HTTP 200 和数字 code: 200,包含 message、requestId、data。采购、续费的成功响应可能仍处于 accepted 或 processing,需要用原订单或操作编号查询最终结果;不能把 HTTP 成功当作资源已交付。动态接口保留原合同:提取可能使用 code: 0,白名单部分失败可能使用 HTTP 200 / 10431,具体成功结构见各接口。
静态错误响应示例(无 data):
{"code":10700,"message":"请求参数无效","requestId":"00000000-0000-4000-8000-000000000001"}
| 字段 | 类型 | 说明 |
|---|---|---|
| code | integer | 数字业务码,定位错误原因 |
| message | string | 服务端结果说明 |
| requestId | string | 静态 API 请求追踪编号,不是幂等编号;动态接口是否包含此字段以接口合同为准 |
静态住宅 API 错误码
以下列出响应体中的业务码 code。成功业务码为 200;订单还需读取 data.status 和逐项结果。
| API 业务码(code) | 含义与恢复方式 |
|---|---|
| 10700 | 参数错误,包括无效 IP、分组名或批量上限;修正后重试 |
| 10001 | 账户令牌无效;检查令牌,不公开令牌内容 |
| 10711 | API 资格不可用或访问拒绝;检查账户资格 |
| 10712 | 必须使用 HTTPS |
| 10207 | 当前交易不可受理;核对订单状态 |
| 10703 | 订单或资源不存在、或不归属当前账户 |
| 10704 | 实例不存在、或不归属当前账户 |
| 10701 | 商品或实例操作能力不可用;重新查询可用商品与能力 |
| 10702 | 可售库存已变化;重新查询库存 |
| 10705 | 同一业务编号参数冲突,或实例已有未完成操作;原编号回查,不能盲目换号重复交易 |
| 10710 | 价格已变化;重新报价并确认金额 |
| 10204 | 可购买余额不足 |
| 10713 | 请求限流;按 Retry-After 等待 |
| 10707 | 服务暂不可用,请联系管理员;先用原业务编号回查,再有限退避重试 |
| 500 | 服务暂不可用,请联系管理员;原因未分类或结果尚未确认时,先查询原订单 |
最终资源状态和逐项 errorCode 属于业务结果,不能仅依赖顶层成功码判断。资金或交易请求结果不明时先回查原编号,避免重复扣费。
动态公开 API 的 HTTP 错误
| HTTP | 业务码 | 说明 |
|---|---|---|
| 200 | 10000 | 业务参数无效(HTTP 200 不等于业务成功) |
| 401 | 10001 | 认证令牌无效 |
| 429 | 10000 | 请求频率超限,按 Retry-After 等待 |
| 200 | 10431 | 批量部分失败,检查 failed_items |
| 401 | 10009 | 认证令牌无效 |
资格与来源
10601:请先完成实名认证。10428:账密来源为中国大陆 IPv4。10429:账密来源为 IPv6。10430:账密来源无法识别。
白名单
10411:当前操作需要来源白名单。10423:来源属于不允许添加的 IPv4 范围。10424:该 IP 已被其他账号占用。10425:该 IP 已在当前账号白名单中。10427:当前白名单不接受 IPv6。10431:批量白名单操作存在失败项。查看success_count、failed_count和failed_items,只处理失败项目。
代理与路由
- HTTP 407:检查账密或来源白名单认证。
10502:代理认证失败。10504:当前代理出口路由不可用,应有限退避后重试。
提交诊断
- 提供业务码、HTTP 状态、请求 ID、时间和脱敏阶段。
- 不提交密码、完整代理 URL 或控制台会话。
同步采购与交付失败
库存不足返回 HTTP 200 / 业务码 10702,提示“当前地区库存不足”;其他明确采购失败返回 HTTP 200 / 业务码 10707,提示“服务暂不可用,请联系管理员”。已创建订单的响应保留订单号、逐项结果和结算金额。订单查询和 Webhook 使用一致的逐项 errorCode、errorMessage、nextAction。遇到 RESULT_UNCONFIRMED 请查询原订单,不要更换编号重复下单。
原因未分类或采购结果无法确认时,业务码统一为 500,提示“服务暂不可用,请联系管理员”。订单的待确认状态和查询指引仍保留,请勿重复下单。
当前购买提示:购买时库存不足或服务无法完成购买,统一返回业务码 10702,提示“当前地区库存不足”。参数、账户余额、访问权限等错误仍按对应业务码返回。若订单仍在处理中或 nextAction 为 query_order,请查询原订单,不要重复购买。
这篇内容解决了你的问题吗?
反馈只用于改进公开文档,不会提交账号或请求信息。