Guides / Error codes

Error codes

Every error shares a single shape: HTTP status + machine-readable type + 7-digit sys_code + bilingual message. Public-API series is 15xxxxx.

Error object shape

error body

{
  "error": {
    "type": "validation_failed",
    "sys_code": 1422001,
    "http_status": 422,
    "message": "service_tier_id not available for lane HK→US",
    "message_zh": "驗證失敗 — 該航線不支援此服務級別",
    "param": "service_tier_id",
    "request_id": "req_K3p9XnQ2Vm4LtRyB"
  }
}

sys_code reference

15xxxxx — Public API error series.

sys_code	HTTP	English message	繁中
1400001	400	invalid_request — malformed JSON body	請求格式錯誤 — JSON 解析失敗
1400002	400	invalid_request — missing required parameter	缺少必填參數
1401001	401	authentication_required — no Bearer token provided	需要驗證 — 缺少 Bearer Token
1401002	401	authentication_failed — key revoked or expired	驗證失敗 — 金鑰已失效
1403001	403	permission_denied — key lacks scope for this resource	無權限 — 金鑰範圍不足
1404001	404	not_found — shipment does not exist	貨件不存在
1404002	404	not_found — tracking number not recognised	追蹤號碼無效
1409001	409	conflict — shipment already past pickup	貨件已取件，無法取消
1409002	409	conflict — idempotency key reused with different body	冪等金鑰重複但內容不同
1422001	422	validation_failed — service_tier_id not available for lane	驗證失敗 — 該航線不支援此服務級別
1422002	422	validation_failed — parcel exceeds dimensional limits	驗證失敗 — 包裹尺寸超限
1429001	429	rate_limited — per-second cap (100/sec)	請求過於頻繁 — 每秒上限
1429002	429	rate_limited — per-day cap (10,000/day)	請求過於頻繁 — 每日上限
1500001	500	server_error — please retry with backoff	伺服器錯誤 — 請使用指數退避重試
1503001	503	service_unavailable — endpoint in preview	服務尚未開放

Every error response also carries an X-Request-Id header — include it when reporting issues.