跳轉到主要內容

​
錯誤處理

Flex Forward API 使用標準 HTTP 狀態碼和結構化的錯誤回應。本頁面涵蓋錯誤格式、狀態碼含義以及處理失敗的指引。

​
錯誤回應格式

API 根據失敗類型回傳兩種錯誤回應格式。 API 根據失敗類型回傳三種錯誤回應格式。了解預期的格式有助於撰寫正確的錯誤解析邏輯。
格式發生時機狀態碼
標準錯誤身份驗證、資源未找到、伺服器錯誤401, 403, 404, 405, 500
驗證錯誤請求本文綱要驗證失敗400
標籤失敗物流業者拒絕標籤請求502（亦含 status: failed 的 201/200）

​
標準錯誤

用於身份驗證失敗、資源未找到和伺服器錯誤： 
{
  "error": "Unauthorized"
}

​
驗證錯誤

用於請求驗證失敗（HTTP 400）。包含帶有欄位級別錯誤資訊的 details 陣列： 
{
  "error": "Validation failed",
  "details": [
    {
      "field": "shipment.shipTo.address.countryCode",
      "message": "must be a valid ISO 3166-1 alpha-2 country code"
    },
    {
      "field": "shipment.parcels[0].weight",
      "message": "must be greater than 0"
    }
  ]
}
details 中的每個條目包含：
欄位說明
field指向無效欄位的點分隔路徑（陣列索引使用括號表示法）
message驗證失敗的人類可讀描述

​
HTTP 狀態碼

狀態含義發生時機可重試
200成功 / 冪等重放GET 請求成功，或使用先前已用過的 idempotencyKey 的 POST不適用
201已建立標籤建立成功不適用
400錯誤請求請求本文驗證失敗否 — 修正請求
401未授權Bearer 令牌缺失或無效否 — 向 Flex Forward 團隊取得有效令牌
403禁止存取令牌有效但無權存取請求的資源否 — 確認帳戶權限
404未找到標籤 ID 或配送帳戶不存在否 — 確認 ID
405方法不允許此端點不支援該 HTTP 方法否 — 檢查方法
500內部伺服器錯誤非預期的伺服器故障是 — 使用退避策略重試
502錯誤閘道物流業者服務回傳錯誤是 — 使用退避策略重試

​
驗證錯誤（400）

驗證錯誤表示請求本文不符合 API 綱要的要求。回應一定包含帶有具體欄位路徑的 details 陣列。 常見原因：
  • 缺少必填欄位（shipment.shipTo、courier、idempotencyKey）
  • 欄位格式無效（國家代碼、電子郵件、電話號碼）
  • 數值無效（重量必須大於 0）
重試前請修正 details 陣列中列出的所有驗證錯誤。由於未建立標籤，400 回應後可以重複使用相同的 idempotencyKey。

​
身份驗證錯誤（401 / 403）

​
401 Unauthorized

Bearer 令牌缺失、格式不正確或已過期： 
{
  "error": "Unauthorized"
}
請確認 Authorization 標頭存在且格式正確：Bearer YOUR_API_TOKEN。

​
403 Forbidden

令牌有效但無權存取請求的資源。當嘗試取得屬於其他帳戶的標籤或追蹤資訊時會發生： 
{
  "error": "Forbidden"
}

​
下游物流業者錯誤（502）

當物流業者服務回傳錯誤時，API 以 HTTP 502 回應。標籤會以 status: failed 保存在資料庫中，並包含物流業者的錯誤詳情： 
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "failed",
  "courier": "yunexpress",
  "courierOrderNumber": null,
  "courierTrackingNumber": null,
  "error": {
    "code": "COURIER_ERROR",
    "message": "Address validation failed at courier"
  }
}
error 物件包含：
欄位說明
code機器可讀的錯誤代碼
message來自物流業者的人類可讀錯誤描述
502 回應表示標籤請求已到達物流業者並被拒絕。重試前請檢視錯誤訊息 — 部分物流業者錯誤（如地址驗證）並非暫時性的，需要修改請求。

​
可重試與不可重試的錯誤

錯誤類型可重試處理方式
400 驗證否根據 details 修正請求本文
401 未授權否向 Flex Forward 團隊取得有效令牌
403 禁止存取否確認對資源的帳戶存取權限
404 未找到否確認標籤 ID 或配送帳戶
500 伺服器錯誤是使用相同的 idempotencyKey 並以退避策略重試
502 物流業者錯誤視情況檢查錯誤訊息 — 暫時性問題可重試，驗證問題不可
推薦的重試策略請參閱冪等性與重試。

​
疑難排解

所有 POST 請求必須包含 Content-Type: application/json。缺少時請求本文將不會被解析，API 會回傳 400 錯誤。
所有請求必須使用 HTTPS。請確認使用正確的環境 URL：https://api.flexforward.com（正式）或 https://sandbox.flexforward.com（開發）。
GET /labels/{id} 和 GET /tracking/{id} 的 id 參數必須是有效的 UUID。傳入追蹤號碼或其他識別碼格式將回傳 404 錯誤。
HTTP 201 或 200 回應中的 status: failed 表示標籤已保存但物流業者拒絕了請求。請檢查 error 物件中的物流業者錯誤訊息。常見原因：無效地址、不支援的目的地，或物流業者帳戶設定問題。