错误与限流

当 API 请求失败时，ShipSaving 会返回结构化的错误响应，包含机器可读的 code 和人类可读的 msg。本页说明错误响应格式、HTTP 状态码、限流机制。

所有 API 响应（包括错误）都使用相同的 JSON 结构：

成功响应：

{
  "code": "ok",
  "msg": "ok",
  "data": { ... }
}

错误响应：

{
  "code": "shipment.address.city_can_not_be_null",
  "msg": "City is required.",
  "data": null
}

字段	类型	说明
`code`	string	成功时为 `"ok"`；失败时为以点分隔的错误码（如 `shipment.buy.pay_shipment_failed`）。
`msg`	string	描述结果的可读消息。
`data`	object / null	成功时包含响应数据；失败时为 `null`。

状态码	含义	触发场景
200	OK	请求成功。注意仍需检查 `code` 字段，`"ok"` 才表示真正成功。
400	Bad Request	请求参数无效、缺少必填字段或违反业务规则。`code` 字段包含具体的错误码。
401	Unauthorized	访问令牌缺失、过期或无效。需通过 `/oauth2/token` 重新获取令牌。
429	请求过于频繁	您的请求频率超过了限流阈值。请降低调用速率后重试。
500	Internal Server Error	服务端发生意外错误。如果持续出现，请联系技术支持。

错误码采用点分隔命名，标识所属的业务域和具体问题：

{domain}.{subdomain}.{detail}

示例：

你可以利用域名前缀在代码中对错误进行分类处理（例如，所有 shipment.address.* 错误表示地址输入有误）。

例外

/oauth2/token 接口遵循 OAuth 2.0 错误格式，不使用上述点分隔命名规则。详见认证。

限流在三个层级生效：

层级	范围	说明
App Key	单个 API Key	每个 `app_key` 有独立的请求配额。某个集成的高频调用不会影响你的其他 Key。
Company	单个账户	同一公司下的所有 API Key 共享一个配额，即使使用多个 Key 也会合并计算。
Global	全平台	全平台的总请求上限。当平台整体负载较高时，即使你的 Key 还有余量，请求也可能被拒绝。

一个请求必须通过所有适用层级的检查。任何一个层级超限，请求都会被拒绝。

限额说明

限额因接口和账户等级而异，且可能随时调整。如果你的集成需要更高的吞吐量，请联系你的客户经理。

当超出限流时，API 返回 HTTP 429，错误码为 common.check.rate_limit：

{
  "code": "common.check.rate_limit",
  "msg": "request too frequent",
  "data": null
}

检查 code 字段，而非仅依赖 HTTP 状态码。
HTTP 200 响应中 "code": "error" 仍然是错误。务必在处理 data 之前确认 code == "ok"。
自动处理认证错误。
401 错误分为两种情况：

凭证错误：如果 /oauth2/token 返回 401 且响应体为 {"error": "invalid_client"}，说明 app_key 或 app_secret 不正确。请检查凭证，不要重试。
访问令牌过期：如果其他 API 接口返回 401 且响应体为空，说明访问令牌已失效。请通过 /oauth2/token 重新获取令牌后重试原始请求。

对瞬态错误实施退避重试。
遇到 common.redis_lock.system_busy、shipment.pay.get_pay_lock_failed 或 common.check.rate_limit 等错误时，使用指数退避策略重试：
```
等待 1s → 重试 → 等待 2s → 重试 → 等待 4s → 重试 → 放弃
```
不要重试校验类错误。
shipment.address.*、shipment.package.*、shipment.custom.* 类别的错误表示输入有误，需修正请求参数后再重试。
使用 platform_uk_id 防止重复下单。
如果在购买面单时遇到超时或不明确的响应，先查询运单状态再决定是否重试。shipment.current_platform_uk_id_already_create_shipment 错误可以防止重复扣费。