错误码表

HTTP code + meta 双码系统，对齐 51tracking / 168tracking 行业规范。

所有错误响应统一格式 {code, meta, message, data}，其中 meta 是业务码。客户端应优先检查 meta，而不是 HTTP status code。

HTTP 状态码（粗分类）

HTTP	meta 范围	含义	客户端行为
`200`	200	成功	正常处理 data
`400`	41xx	请求参数错误（业务）	检查 message 修复请求
`401`	401	身份验证失败	检查 API Key
`403`	403	禁止访问（跨账号）	权限错误
`404`	4102	资源不存在	检查 id 是否正确
`429`	429	超出请求限制	退避 120s 后重试
`500`	51x	服务器错误	记录错误码 + 联系支持

业务码 41xx（参数错误）

meta	HTTP	含义	常见原因
`4101`	400	物流单号已存在	同一单号重复注册（不会重复扣 quota）
`4102`	400	物流单号不存在	查询时该单号未注册到当前账号
`4103`	400	批量超过 40 个	单次批量上限 40，超出被拒（不扣 quota）
`4110`	400	tracking_number 不符合规则	长度不在 4-40 之间
`4111`	400	tracking_number 必填	JSON body 缺字段
`4112`	400	查询 ID 无效	tracking id 拼写错
`4113`	400	retrack 太频繁	间隔 < 1 小时
`4120`	400	courier_code 无效	不在支持列表：usps/ups/fedex/dhl/sf-express/yto
`4130`	400	请求参数格式无效	JSON 解析失败 / 类型错 / URL 不合法（webhook）
`4190`	400	查询额度不足	当月 quota 已用完

业务码 51xx（服务器错误）

meta	HTTP	含义	客户端行为
`511`	500	上游查询失败	retry-friendly，等 30s 后重试
`512`	500	数据库错误	联系支持，提供 request id
`513`	500	内部异常	联系支持，提供完整 request body

响应示例

成功响应（meta=200）

{
  "code": 200,
  "meta": 200,
  "message": "请求响应成功。",
  "data": {
    "id": "f44cba625aa841eb7225f511",
    "tracking_number": "9205512345600001234567",
    "carrier": "usps",
    "status": "查询中"
  }
}

业务错误（meta=4111）

{
  "code": 4111,
  "meta": 4111,
  "message": "物流单号(tracking_number)为必填字段。",
  "data": null
}

认证错误（meta=401）

{
  "code": 401,
  "meta": 401,
  "message": "身份验证失败或没有权限。",
  "data": null
}

额度不足（meta=4190）

{
  "code": 4190,
  "meta": 4190,
  "message": "当前查询额度不足。",
  "data": null
}

限流（meta=429）

{
  "code": 429,
  "meta": 429,
  "message": "超出 API 请求限制，请稍后重试。",
  "data": null
}

客户端错误处理建议

import requests

def call_api(method, url, **kwargs):
    r = requests.request(method, url, timeout=10, **kwargs)
    body = r.json()
    meta = body.get('meta')

    # 成功
    if meta == 200:
        return body['data']

    # 限流：退避 120s
    if meta == 429:
        time.sleep(120)
        return call_api(method, url, **kwargs)

    # quota 用完：抛异常，让上层决定升级 plan
    if meta == 4190:
        raise QuotaExceededError(body['message'])

    # 4xx 业务错误：抛异常 + 完整 meta 信息
    if 4100 <= meta < 4200:
        raise BusinessError(meta, body['message'])

    # 5xx 服务器错误：可重试 3 次（指数回退）
    if 510 <= meta < 520:
        for attempt in range(3):
            time.sleep(2 ** attempt)
            try:
                return call_api(method, url, **kwargs)
            except BusinessError:
                raise
        raise ServerError(meta, body['message'])

    raise UnknownError(meta, body)