文档目录点击展开 ▼

首页开放平台文档错误码大全

错误码大全

物流巴巴开放平台统一使用 4 位数字错误码，按首位划分大类。所有错误响应都包含 request_id，提工单时附上可快速定位。

错误响应结构

{
  "code": 2002,
  "msg": "Signature verification failed",
  "detail": "expected signature does not match",
  "request_id": "f8a92c1e-3b4d-4f1a-b3a7-9c2e1f6d8b3a"
}

扣费规则

只有 code = 0 的成功响应扣积分
HTTP 4xx / 5xx 全部不扣积分
业务失败（如港口不存在、查询无结果）虽然 HTTP 200 但 code ≠ 0，不扣积分
客户端超时（10 秒未收到响应）不扣积分

成功

业务调用成功，积分扣减。

code	HTTP	含义	客户应对
0	200	成功	正常处理数据

1xxx 参数错误

请求参数有误，不扣积分。

code	HTTP	含义	客户应对
1001	400	参数缺失 / 类型不合法	检查必填字段、类型、长度
1002	400	船公司/航司存在多个匹配（歧义）	用响应中的 candidates 字段选择具体代码后重发。注：起运港/目的港多匹配已不再返回此码，改为自动返回各匹配港口的运价
1003	400	参数取值超出允许范围	检查 page/limit/weight 等数值边界
1004	400	组合参数冲突	阅读接口文档检查互斥字段

2xxx 鉴权错误

鉴权失败，不扣积分。建议直接告警而非重试。

code	HTTP	含义	客户应对
2001	401	AppKey 不存在或已吊销	不要重试，到控制台检查应用状态
2002	401	签名校验失败	对照鉴权页排查签名算法（METHOD/PATH/JSON 空格）
2003	401	时间戳过期（>±300 秒）	同步系统 NTP 时间
2004	401	Nonce 重复（10 分钟内已用过）	重新生成 nonce 重试一次
2005	401	请求 IP 不在白名单	到控制台「应用管理」添加 IP 白名单
2006	401	请求头缺失 X-Awice-* 字段	检查 4 个必填请求头是否齐全

3xxx 计费错误

套餐 / 余额问题，不扣积分。建议直接告警告知用户。

code	HTTP	含义	客户应对
3001	402	积分不足（余额用完，或免费体验包还没领取）	不要重试；到控制台领取体验包或购买套餐。响应含 trial_available 字段，可程序化判断该引导领取还是购买
3003	402	字典查询需要有效套餐（未订阅账号不开放）	领取体验包或购买套餐；仅做下拉选项可改用免费不限次的 dict/popular
3004	402	套餐已过期（响应含 expired_at / frozen_credit）	续费或购买新套餐。注意：套餐到期时未用完的积分会一并失效

4xxx 限流

QPS 超限，不扣积分。响应头 Retry-After 告知建议重试时间。

code	HTTP	含义	客户应对
4001	429	QPS 超限	指数退避重试，参考 Retry-After 头
4002	429	当日调用次数超出软限	24h 后恢复或联系商务提升上限

5xxx 服务端错误

服务端问题，不扣积分。建议重试 1-2 次。

code	HTTP	含义	客户应对
5001	500	服务内部错误	重试 1 次，仍失败提交工单（附 request_id）
5002	503	上游服务不可用（仅快递接口）	重试 2 次，间隔 2 秒
5003	504	上游响应超时	增大客户端 timeout 后重试

重试策略建议

code 段	是否重试	建议策略
1xxx	不重试	参数错误，重试无意义，告警人工排查
2xxx	不重试	鉴权问题（仅 2004 Nonce 可重试一次）
3xxx	不重试	套餐问题，告警通知运营
4xxx	可重试	指数退避：1s / 2s / 4s，参考 Retry-After
5xxx	可重试	最多 2 次，间隔 1-3 秒，附 request_id 报工单

下一步：海运整柜 FCL 运价查询

错误码大全 - 物流巴巴开放平台文档 | 5688.cn