错误码
atoship API 采用标准的 HTTP 响应状态码来表示 API 请求成功或失败。2xx 范围的状态码表示成功， 4xx 表示客户端错误，5xx 表示服务器错误。
HTTP 状态码
成功状态码
请求成功
资源创建成功
客户端错误
请求参数无效
API 密钥无效或缺失
余额不足或支付失败
API 密钥缺少所需权限
资源不存在
请求数据校验错误
超出速率限制
服务器错误
我们这边出了点问题
API 暂时不可用
错误对象
每个错误都会返回一个带 error 对象的 JSON。 请依据 HTTP 状态码和 error.code 分支处理 —— 这两项在每个错误响应里都有。
error.codestring供程序识别的错误码，全大写下划线（例如 "RATE_LIMIT_EXCEEDED"）。分支判断请用这个字段。
error.messagestring供人阅读的说明。可以直接展示给用户；不要去解析它，措辞会变。
error.detailsarray（可选）400 时的校验器输出。每项带 path 和 message，具体形状取决于出错的字段。
error.paramstring（可选）能够指明单一出错字段时给出（例如 "to_address.phone"）。
error.retryAfternumber（可选）仅 429 时出现，表示需要等待的秒数。Retry-After 响应头里是同一个值。
响应里还带有 object，部分接口带 mode。这两个字段并非每个接口都有，请不要依据它们分支。 不存在 type 和 request_id 字段。
处理错误
通过状态码判断错误的类别
全大写下划线的 code 是稳定标识 —— 匹配它，不要匹配 message 文本
将 message 展示给用户，提供可操作的反馈
等待 error.retryAfter 秒（或读 Retry-After 响应头）后再重试
| 1 | { |
| 2 | "object": "Error", |
| 3 | "error": { |
| 4 | "code": "VALIDATION_ERROR", |
| 5 | "message": "Invalid request data", |
| 6 | "details": [ |
| 7 | { |
| 8 | "code": "custom", |
| 9 | "path": ["parcel"], |
| 10 | "message": "Send `parcel` for a single box, or `parcels` for a multi-piece shipment." |
| 11 | } |
| 12 | ] |
| 13 | } |
| 14 | } |
各接口还有自己的错误码 —— 购买面单可能返回 DESTINATION_PHONE_REQUIRED 或 CUSTOMS_REQUIRED。遇到不认识的 code， 按它的 HTTP 状态码大类处理。
额度属于你的组织，不属于单个密钥 —— 账号下所有 API 密钥和用户共用同一份额度。
按固定窗口计数。日额度在 UTC 00:00 重置，429 响应会带 Retry-After 头。
需要更高的限额？请联系 [email protected] —— 限额按账号单独调整。