错误处理
调用失败时,返回一个 RFC 9457 Problem Details 格式的 JSON 对象,内容类型为 application/problem+json:
{ "type": "https://developers.ga-oms.com/errors/not_found", "title": "Not found", "status": 404, "code": "not_found", "detail": "No such shipment.", "request_id": "req_01JCX7M4Z9Q8R6T5V3W2Y1N0AB"}| 字段 | 用途 |
|---|---|
code |
错误代码,固定不变。程序请根据它判断,不要根据文字说明 |
detail |
一句话说明错误原因,供人阅读 |
type |
本站对应该错误代码的说明页面 |
request_id |
请求 ID。发给我们即可定位到那一次调用。每个响应的 Request-Id 响应头中也有 |
errors |
部分错误代码会带有:逐条列出问题;问题出在某个字段时带有 field |
| 状态码 | 代码 | 含义 |
|---|---|---|
| 400 | invalid_request |
参数缺失或无效,detail 会指出是哪个参数 |
| 401 | invalid_key |
未提供密钥,或密钥无效 |
| 401 | wrong_environment |
测试密钥用于正式环境,或正式密钥用于测试环境 |
| 401 | account_closed |
密钥所属的账号已关闭 |
| 403 | https_required |
调用使用了 http |
| 403 | missing_scope |
密钥没有该操作的权限 |
| 403 | forbidden |
该账号无权进行此操作 |
| 404 | not_found |
您的账号下不存在该对象 |
| 409 | order_exists |
该主单已有您的订单,响应中带有该订单的 id |
| 409 | conflict |
处理请求期间,订单已被更新 |
| 413 | too_large |
请求体超过该接口允许的大小 |
| 422 | order_invalid |
订单未通过校验,errors 列出全部问题 |
| 429 | rate_limited |
同一密钥一分钟内调用超过 120 次 |
| 429 | too_many_wrong_keys |
您的 IP 地址短时间内发来大量密钥错误的调用 |
| 500 | failed |
我们的系统故障。请重试;如果反复出现,请把 request_id 发给我们 |
| 503 | busy |
没有保存任何数据,请在 Retry-After 之后重新提交 |
错误代码可能增加。遇到不认识的代码,请按状态码处理:4xx 表示需要修正调用,5xx 表示稍后重试。