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

錯誤處理

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

錯誤回應格式

API 根據失敗類型回傳四種錯誤回應格式。了解預期的格式有助於撰寫正確的錯誤解析邏輯。

格式	發生時機	狀態碼
標準錯誤	不支援的物流業者/產品、身份驗證、資源未找到、衝突、速率限制或伺服器錯誤	400, 401, 403, 404, 409, 429, 500；GET 端點為 502
驗證錯誤	請求本文綱要驗證失敗	400
標籤失敗	物流業者拒絕標籤請求；`status: failed` 的 `LabelResponse`	`POST /labels` 的 502，或冪等重放回傳已儲存的失敗結果時的 200
失敗標籤讀取	讀取物流業者提交失敗的標籤；`LabelFailedResponse`	`GET /labels/{id}` 與 `GET /tracking/{id}` 的 422

標準錯誤

用於不支援的物流業者/產品、身份驗證失敗、衝突、資源未找到和伺服器錯誤等情況。格式為 { "error": string, "code"?: string }：

{
  "error": "Label not found"
}

error 文字僅供參考，可能隨時變更而不另行通知。請根據 HTTP 狀態碼，以及存在時的 code，來判斷分支邏輯 — 切勿依賴訊息文字本身。 code 欄位會在部分錯誤回應中提供。IDEMPOTENCY_CONFLICT 與 DUPLICATE_CUSTOMER_ORDER_NUMBER 可區分 HTTP 409 衝突。

`code`	意義
`IDEMPOTENCY_CONFLICT`	HTTP 409：該金鑰曾以不同的請求本文使用。請以原始本文重放，或為變更後的請求使用新金鑰。
`DUPLICATE_CUSTOMER_ORDER_NUMBER`	HTTP 409：該訂單編號已存在於您的帳戶中。請取得該標籤，或為新標籤使用不同的訂單編號。
`COURIER_ERROR`	物流業者拒絕了標籤請求。此代碼在 HTTP 502 的標籤回應中巢狀於 `error.code`，或在失敗標籤讀取時以 `errorCode` 回傳。

code 為選填，也可能出現未知值。沒有代碼時請依 HTTP 狀態碼處理。

驗證錯誤

用於請求驗證失敗（HTTP 400）。包含帶有欄位級別錯誤資訊的 details 陣列：

{
  "error": "Validation failed",
  "details": [
    {
      "field": "shipment.parcels.0.weight",
      "message": "must be >= 0"
    }
  ]
}

details 中的每個條目包含：

欄位	說明
`field`	指向無效欄位的點分隔路徑。陣列索引以點分隔的數字表示，例如 `shipment.parcels.0.weight`。
`message`	驗證失敗的人類可讀描述

只會回傳第一個驗證錯誤。修正後重新送出即可看到下一個錯誤。

HTTP 狀態碼

狀態	含義	發生時機	可重試
200	成功 / 冪等重放	GET 請求成功，或 `POST /labels` 以相同金鑰與本文重放。儲存結果可能為 `status: failed`	不適用
201	已建立	標籤建立成功	不適用
400	錯誤請求	請求驗證失敗或不支援的物流業者/產品	否 — 有 `details` 時先查看，否則查看 `error` 與 `code` 後修正
401	未授權	`x-rr-apikey` / `x-rr-apitoken` 缺失或無效	否 — 至 User Portal 取得有效認證資訊
403	禁止存取	認證資訊有效但帳戶不被允許（例如遭封鎖）	否 — 確認帳戶權限
404	未找到	標籤 ID 或配送帳戶不存在	否 — 確認 ID
409	衝突	以不同本文重複金鑰，或訂單編號重複	否 — 依 `code` 使用原本文/新金鑰，或選擇其他訂單編號
422	無法處理的實體	標籤存在但物流業者提交失敗；無文件或追蹤資料可用（`GET /labels/{id}`、`GET /tracking/{id}`）	否 — 建立新標籤
429	請求過多	已超出帳戶的請求速率上限。所有端點均已宣告此回應，讓用戶端可在正式啟用前實作對應處理（請參閱速率限制）	是 — 等待 `Retry-After` 標頭中的秒數後再重試
500	內部伺服器錯誤	非預期的伺服器故障	是 — 使用退避策略重試
502	錯誤閘道	物流業者拒絕標籤請求；標籤以 `status: failed` 儲存	使用相同 `idempotencyKey` 不可 — 請先修正原因，再送出新請求（參閱重試失敗的標籤）

標籤建立結果的判讀

POST /labels 在 200、201 與 502 時都回傳相同的 LabelResponse 結構。HTTP 狀態碼說明這次呼叫是建立了標籤、重放了先前的嘗試，還是被物流業者拒絕。status 欄位則說明標籤是否存在。

在 POST /labels 上，請依據 status 欄位而非 HTTP 狀態碼進行分支處理。即使第一次嘗試在物流業者端失敗，冪等重放仍會回傳 HTTP 200，因此 200 回應可能帶有 status: failed。

HTTP	`status`	`error`	意義	處理方式
201	`created`	`null`	這次呼叫已在物流業者端建立標籤	儲存 `id`，繼續進行文件取得與追蹤
200	`created`	`null`	重放先前成功的嘗試	與 201 相同 — 未建立新標籤
200	`failed`	物件	重放先前被物流業者拒絕的嘗試	請勿以相同金鑰重試；參閱重試失敗的標籤
502	`failed`	物件	物流業者拒絕了此請求；此次嘗試已綁定到您的 `idempotencyKey` 儲存	讀取 `error.message`，修正請求，再以新的 `idempotencyKey` 與 `customerOrderNumber` 重新送出

驗證錯誤（400）

綱要驗證錯誤表示請求本文不符合 API 的要求，並包含帶有具體欄位路徑的 details 陣列。其他 HTTP 400 錯誤則使用不含 details 的標準錯誤格式。常見原因：

缺少必填欄位（shipment.shipTo、courier、idempotencyKey）
欄位型別或長度錯誤（例如 countryCode 必須恰好為 2 個字元）
數值為負（weight 與尺寸不得為負數）
order.customerOrderNumber 無效（最多 40 個字元，只能使用 ASCII 英文字母、數字、-、_）
不支援的 label.format（請使用 PDF 或 PNG）或商品 unitPrice.currency（僅接受 USD）

重試前請修正回報的錯誤。由於未建立標籤，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

認證資訊有效，但帳戶不被允許呼叫 API（例如遭封鎖的帳戶）：

{
  "error": "Forbidden: account is blocked"
}

屬於其他帳戶的標籤或追蹤記錄會回傳 404，而非 403。

下游物流業者錯誤 502 與 422

當 POST /labels 執行期間物流業者服務回傳錯誤時，API 以 HTTP 502 回應。標籤會以 status: failed 保存在資料庫中，並包含物流業者的錯誤詳情：

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customerOrderNumber": "N-2026-05-27-TEST-03",
  "status": "failed",
  "courier": "yunexpress",
  "courierOrderNumber": null,
  "courierTrackingNumber": null,
  "error": {
    "code": "COURIER_ERROR",
    "message": "Address validation failed at courier"
  }
}

error 物件包含：

欄位	說明
`code`	機器可讀的錯誤代碼
`message`	來自物流業者的人類可讀錯誤描述

502 回應表示標籤請求已到達物流業者並被拒絕。重試前請檢視錯誤訊息 — 部分物流業者錯誤（如地址驗證）並非暫時性的，需要修改請求。

之後對失敗標籤呼叫 GET /labels/{id} 或 GET /tracking/{id} 時，會回傳 HTTP 422 及 LabelFailedResponse 內容 — 該標籤無文件或追蹤資料可用：

{
  "error": "Label creation failed",
  "errorCode": "COURIER_ERROR",
  "errorMessage": "Address validation failed at courier"
}

可重試與不可重試的錯誤

錯誤類型	可重試	處理方式
400 錯誤請求	否	有 `details` 時先查看，否則查看 `error` 與 `code` 後修正
401 未授權	否	至 User Portal（Settings → Signing Key and API Token）取得有效認證資訊
403 禁止存取	否	確認對資源的帳戶存取權限
404 未找到	否	確認標籤 ID 或配送帳戶
409 衝突	否	若為 `IDEMPOTENCY_CONFLICT`，請使用原本文或新金鑰；若為 `DUPLICATE_CUSTOMER_ORDER_NUMBER`，請取得現有標籤或選擇其他訂單編號
422 無法處理的實體	否	標籤的物流業者提交失敗 — 建立新標籤
429 請求過多	是	等待 `Retry-After` 秒後，使用相同的 `idempotencyKey` 重試
500 伺服器錯誤	是	使用相同的 `idempotencyKey` 並以退避策略重試
502 物流業者錯誤	使用相同金鑰不可	請先修正原因，再以新的 `idempotencyKey` 與 `customerOrderNumber` 送出新請求 — 參閱重試失敗的標籤

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

疑難排解

缺少 Content-Type 標頭

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

基礎 URL 錯誤或使用 HTTP

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

找不到識別碼

GET /labels/{id} 和 GET /tracking/{id} 的 id 參數接受標籤 UUID 或您的 customerOrderNumber。傳入其他值，或屬於其他帳戶的識別碼，將回傳 404 錯誤。

標籤已建立但狀態為 failed

status: failed 的回應會由 POST /labels 以 HTTP 502 回傳（若以相同 idempotencyKey 重放則為 HTTP 200），之後讀取該標籤則會回傳 HTTP 422。請檢查 error 物件（讀取時為 LabelFailedResponse 內容）中的物流業者錯誤訊息。常見原因：無效地址、不支援的目的地，或物流業者帳戶設定問題。

快速開始

指南

使用場景指南

平台

錯誤處理

錯誤處理

錯誤回應格式

標準錯誤

驗證錯誤

HTTP 狀態碼

標籤建立結果的判讀

驗證錯誤（400）

身份驗證錯誤（401 / 403）

401 Unauthorized

403 Forbidden

下游物流業者錯誤 502 與 422

可重試與不可重試的錯誤

疑難排解

​錯誤處理

​錯誤回應格式

​標準錯誤

​驗證錯誤

​HTTP 狀態碼

​標籤建立結果的判讀

​驗證錯誤（400）

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

​401 Unauthorized

​403 Forbidden

​下游物流業者錯誤 502 與 422

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

​疑難排解

錯誤處理

錯誤回應格式

標準錯誤

驗證錯誤

HTTP 狀態碼

標籤建立結果的判讀

驗證錯誤（400）

身份驗證錯誤（401 / 403）

401 Unauthorized

403 Forbidden

下游物流業者錯誤 502 與 422

可重試與不可重試的錯誤

疑難排解