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 (100,000/day, resets 00:00 HKT)	請求過於頻繁 — 每日上限（香港時間 00:00 重置）
1500001	500	server_error — please retry with backoff	伺服器錯誤 — 請使用指數退避重試
1500022	409	conflict — shipment booked through a partner carrier channel; contact support to cancel	貨件經合作通道發出，須聯絡客服協助取消
1500023	502	bad_gateway — the label exists but could not be downloaded, retry shortly	面單存在但下載失敗，請稍後重試
1500024	503	service_unavailable — label has not finished generating yet, retry shortly	面單尚未生成完成，請稍後重試
1500025	400	invalid_request — sales_platform_name is required for shipments to Japan (JP)	寄往日本的訂單必須填寫 sales_platform_name（銷售平台名稱）
1500026	400	invalid_request — VOEC_PREPAY_DISABLED: carrier VOEC prepay for Norway is not yet available	VOEC 代繳服務尚未開放
1500027	400	invalid_request — VOEC_PREPAY_CONFLICT: voec_prepay is mutually exclusive with tax_number, ioss_number and vat_prepay	VOEC 代繳與 VOEC 號碼／IOSS 號碼／歐盟代繳不可同時提供
1500028	400	invalid_request — VOEC_PREPAY_UNSUPPORTED: the selected service does not offer VOEC prepaid service — supply a VOEC number or choose another service	所選服務不提供 VOEC 代繳
1500029	400	invalid_request — TAX_NUMBER_REQUIRED: tax_number is required for shipments to Norway (NO), or set voec_prepay to true	寄往挪威的訂單必須填寫 VOEC／稅務識別碼，或選用 VOEC 代繳服務
1500030	400	invalid_request — HS_CODE_BR_8_DIGITS_REQUIRED: every item must have an hs_code of exactly 8 digits for shipments to Brazil (BR)	寄往巴西的訂單，每個品項的 HS Code 必須為 8 位數字（巴西 NCM）
1500031	400	invalid_request — INSURANCE_UNSUPPORTED: the selected service does not offer insurance — remove INSURANCE from selected_surcharges or choose another service	所選服務不支援保價
1500032	409	conflict — SHIPMENT_CANCEL_INTERCEPT_IN_PROGRESS: an interception request is in progress; withdraw it on the shipment page in the Merdi portal before cancelling	訂單有處理中的攔截申請，須先在 Merdi 網頁撤回才可取消
1500033	400	invalid_request — CL_TAX_NUMBER_REQUIRED: tax_number (the recipient's RUT) is required for shipments to Chile (CL)	寄往智利的訂單必須填寫收件人 RUT（智利稅號）
1500034	400	invalid_request — COD_NOT_AVAILABLE: payment_type "cod" (cash on delivery) is not available yet — use "prepaid"	貨到付款服務暫未開放，請改用預付（prepaid）
1503001	503	service_unavailable — endpoint in preview	服務尚未開放

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