此頁面由英文翻譯而成。英文版為官方權威來源。如翻譯內容有任何不一致之處，請以英文版為準。

錯誤處理

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	未授權	`x-rr-apikey` / `x-rr-apitoken` 缺失或無效	否 — 至 User Portal 取得有效認證資訊
403	禁止存取	認證資訊有效但無權存取請求的資源	否 — 確認帳戶權限
404	未找到	標籤 ID 或配送帳戶不存在	否 — 確認 ID
405	方法不允許	此端點不支援該 HTTP 方法	否 — 檢查方法
500	內部伺服器錯誤	非預期的伺服器故障	是 — 使用退避策略重試
502	錯誤閘道	物流業者服務回傳錯誤	是 — 使用退避策略重試

驗證錯誤（400）

驗證錯誤表示請求本文不符合 API 綱要的要求。回應一定包含帶有具體欄位路徑的 details 陣列。常見原因：

缺少必填欄位（shipment.shipTo、courier、idempotencyKey）
欄位格式無效（國家代碼、電子郵件、電話號碼）
數值無效（重量必須大於 0）

重試前請修正 details 陣列中列出的所有驗證錯誤。由於未建立標籤，400 回應後可以重複使用相同的 idempotencyKey。

身份驗證錯誤（401 / 403）

401 Unauthorized

x-rr-apikey 或 x-rr-apitoken 標頭缺失或無效：

{
  "error": "Unauthorized"
}

請確認兩個標頭皆存在：

x-rr-apikey: YOUR_API_KEY
x-rr-apitoken: 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 物流業者錯誤	視情況	檢查錯誤訊息 — 暫時性問題可重試，驗證問題不可

推薦的重試策略請參閱冪等性與重試。

疑難排解

缺少 Content-Type 標頭

所有 POST 請求必須包含 Content-Type: application/json。缺少時請求本文將不會被解析，API 會回傳 400 錯誤。

基礎 URL 錯誤或使用 HTTP

所有請求必須使用 HTTPS。請確認使用正確的環境 URL：https://api.flexforward.com（正式）或 https://sandbox.flexforward.com（開發）。

標籤 ID 的 UUID 格式無效

GET /labels/{id} 和 GET /tracking/{id} 的 id 參數必須是有效的 UUID。傳入追蹤號碼或其他識別碼格式將回傳 404 錯誤。

標籤已建立但狀態為 failed

HTTP 201 或 200 回應中的 status: failed 表示標籤已保存但物流業者拒絕了請求。請檢查 error 物件中的物流業者錯誤訊息。常見原因：無效地址、不支援的目的地，或物流業者帳戶設定問題。

快速開始

指南

使用場景指南

平台

錯誤處理

錯誤處理

錯誤回應格式

標準錯誤

驗證錯誤

HTTP 狀態碼

驗證錯誤（400）

身份驗證錯誤（401 / 403）

401 Unauthorized

403 Forbidden

下游物流業者錯誤（502）

可重試與不可重試的錯誤

疑難排解

​錯誤處理

​錯誤回應格式

​標準錯誤

​驗證錯誤

​HTTP 狀態碼

​驗證錯誤（400）

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

​401 Unauthorized

​403 Forbidden

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

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

​疑難排解

錯誤處理

錯誤回應格式

標準錯誤

驗證錯誤

HTTP 狀態碼

驗證錯誤（400）

身份驗證錯誤（401 / 403）

401 Unauthorized

403 Forbidden

下游物流業者錯誤（502）

可重試與不可重試的錯誤

疑難排解