错误码
atoship API 采用标准的 HTTP 响应状态码来表示 API 请求成功或失败。2xx 范围的状态码表示成功， 4xx 表示客户端错误，5xx 表示服务器错误。
HTTP 状态码
成功状态码
200
OK
请求成功
201
Created
资源创建成功
客户端错误
400
Bad Request
请求参数无效
401
Unauthorized
API 密钥无效或缺失
402
Payment Required
余额不足或支付失败
403
Forbidden
API 密钥缺少所需权限
404
Not Found
资源不存在
422
Unprocessable Entity
请求数据校验错误
429
Too Many Requests
超出速率限制
服务器错误
500
Internal Server Error
我们这边出了点问题
503
Service Unavailable
API 暂时不可用
错误对象
所有错误都会返回一个具有以下结构的 JSON 对象：
typestring错误类别（例如 "invalid_request_error"）
codestring供程序识别的错误码
messagestring供人阅读的错误说明
paramstring（可选）导致错误的参数
request_idstring用于排查问题的唯一请求 ID
处理错误
检查 HTTP 状态码
通过状态码判断错误的类别
解析错误对象
读取错误的 type 和 code 以便程序化处理
展示错误信息
将 message 展示给用户，提供可操作的反馈
记录 request_id
联系客服时请附上 request_id
ERROR
响应示例| 1 | { |
| 2 | "error": { |
| 3 | "type": "invalid_request_error", |
| 4 | "code": "invalid_parameter", |
| 5 | "message": "Invalid address: zip code is required", |
| 6 | "param": "to_address.zip", |
| 7 | "request_id": "req_abc123def456" |
| 8 | } |
| 9 | } |
错误类型
invalid_request_error参数无效
authentication_error认证失败
validation_error校验失败
rate_limit_error请求过于频繁
api_error服务器错误
carrier_error承运商问题
速率限制
标准接口100 req/min
创建面单60 req/min
运费查询120 req/min
物流追踪200 req/min