错误码对照表
失败响应的 code 与 HTTP 状态码一致，error.code 为机器可读标识。请以 error.code 作为程序判断依据，不要依赖 message 文案。
| HTTP | error.code | 含义 | 排查建议 |
|---|---|---|---|
| 401 | missing_headers | 缺少鉴权请求头 | 确认同时发送 X-Access-Key、X-Timestamp、X-Signature，注意代理或网关是否过滤了自定义头。 |
| 401 | auth_failed | 时间戳超窗 / 密钥不存在 / 签名错误 | 检查服务器时间是否准确（±300 秒）；核对 Access Key；确认 HMAC 密钥为 SHA256(Secret) 且使用原始请求体签名。 |
| 403 | auth_failed | 密钥禁用或过期 / IP 不在白名单 | 会员中心查看密钥状态与有效期；核对调用出口公网 IP 是否与白名单一致。 |
| 403 | forbidden_scope | 密钥未授权该接口 | 在会员中心编辑密钥，勾选对应 scope，或重新创建密钥并选择全部范围。 |
| 404 | invalid_endpoint | 接口路径不合法 | 路径必须为 /api.php/v1/{module}/{action}，三段齐全且版本为 v1。 |
| 404 | module_not_found | 模块未开放 | 仅 account、order、domain 已开放；产品/服务/通知模块暂无 API。 |
| 429 | rate_limited | 超过频率限制 | 单密钥与单 IP 均限制 10 次/秒。请降低并发、增加退避重试，或拆分多个密钥分担流量。 |
| 500 | controller_error | 参数校验失败或服务端异常 | 读取 message 定位：missing id、order not found、product_id required、product not available、keywords required。若为服务端异常，请携带请求时间与订单号联系技术支持。 |
| 503 | api_disabled | 开放平台已关闭 | 管理员关闭了 API 全局开关，请联系大鹏云客服或稍后重试。 |
关于 500 controller_error：V1 版本对业务校验失败（如订单不存在、产品不可用）统一以 HTTP 500 + controller_error 返回，具体原因在 message 中。请勿将其一律视为服务端崩溃；建议记录完整响应体用于排查。
频率限制
| 限制维度 | 阈值 | 说明 |
|---|---|---|
| 单密钥 | 10 次 / 秒 | 以密钥 ID 为维度计数，窗口为 1 秒。 |
| 单 IP | 10 次 / 秒 | 以调用来源 IP 为维度计数，同一 IP 下的多个密钥共享该限制。 |
| 超出限制 | 429 rate_limited | 超限的请求直接拒绝，不会进入业务处理。计数按请求次数累计。 |
| 建议 | — | 批量同步场景请错峰调度，单批次请求间保留间隔；收到 429 后采用指数退避（如 1s、2s、4s）重试。 |
注意事项
- Secret 保管：仅保存在服务端或密钥管理系统；不要在日志、前端、App、代码仓库中出现。怀疑泄露立即吊销。
- 时间同步：调用服务器需启用 NTP。时间偏差超过 300 秒会导致全部请求鉴权失败。
- 签名原文：必须对最终发送的请求体字节签名，避免 JSON 重新序列化导致键顺序、空格、转义差异。
- 幂等控制：order/create 无幂等键，超时后请先查询订单列表确认，再决定是否重试；其余接口为只读，可安全重试。
- 重试策略：401/403/404 不应自动重试（需修正配置）；429 与 500 可有限重试（建议最多 3 次，指数退避），仍失败则记录响应体并告警。
- 数据隔离：所有查询自动按密钥所属客户过滤，跨客户访问一律返回「不存在」，无需也不应传入 client_id。
- 金额精度：金额按十进制字符串解析与存储，禁止用浮点数做累计与对账。
- 权限最小化：按业务需要勾选 scope，避免使用全量权限密钥；可分别创建只读密钥与下单密钥。
- IP 白名单：生产环境建议固定出口 IP 并启用白名单，降低密钥滥用风险。
- 日志留存：后台「API 管理」可查看调用记录与错误统计，建议将本地的请求时间、接口、响应 code 一并留存便于对账。
对接检查清单
| 序号 | 检查项 | 通过标准 |
|---|---|---|
| 1 | 密钥已创建并保存 Secret | Secret 已落库到凭据系统，页面关闭后不再依赖明文展示。 |
| 2 | scope 覆盖所需接口 | 调用目标接口不再返回 forbidden_scope。 |
| 3 | 服务器时间准确 | 与标准时间偏差小于 60 秒。 |
| 4 | 签名实现正确 | GET 与 POST 均能通过鉴权，POST 含中文时签名一致。 |
| 5 | 错误处理完善 | 按 error.code 分支处理，429 有退避，401/403 有告警。 |
| 6 | 订单幂等保护 | 下单超时后先查询再重试，避免重复订单。 |
| 7 | 金额精度处理 | 金额以字符串/定点小数处理，对账无偏差。 |
技术支持
如对接过程中遇到问题，请提供请求时间、接口路径、HTTP 状态码、error.code 与 message，通过大鹏云官网在线客服或工单系统联系我们。
为保护账号安全，请勿在工单中粘贴完整 Secret。
—— 大鹏云API开发者文档 V1.0 · 大鹏云有限公司 · www.dapengcloud.com ——