> ## Documentation Index
> Fetch the complete documentation index at: https://openapidocs.flexforwardship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 錯誤處理

> HTTP 狀態碼、錯誤回應格式與疑難排解指南

<Note>
  此頁面由英文翻譯而成。[英文版](/introduction)為官方權威來源。如翻譯內容有任何不一致之處，請以英文版為準。
</Note>

# 錯誤處理

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

## 錯誤回應格式

API 根據失敗類型回傳兩種錯誤回應格式。

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

| 格式   | 發生時機             | 狀態碼                                |
| ---- | ---------------- | ---------------------------------- |
| 標準錯誤 | 身份驗證、資源未找到、伺服器錯誤 | 401, 403, 404, 405, 500            |
| 驗證錯誤 | 請求本文綱要驗證失敗       | 400                                |
| 標籤失敗 | 物流業者拒絕標籤請求       | 502（亦含 `status: failed` 的 201/200） |

### 標準錯誤

用於身份驗證失敗、資源未找到和伺服器錯誤：

```json theme={null}
{
  "error": "Unauthorized"
}
```

### 驗證錯誤

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

```json theme={null}
{
  "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）

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

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

### 401 Unauthorized

Bearer 令牌缺失、格式不正確或已過期：

```json theme={null}
{
  "error": "Unauthorized"
}
```

請確認 `Authorization` 標頭存在且格式正確：`Bearer YOUR_API_TOKEN`。

### 403 Forbidden

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

```json theme={null}
{
  "error": "Forbidden"
}
```

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

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

```json theme={null}
{
  "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` | 來自物流業者的人類可讀錯誤描述 |

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

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

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

推薦的重試策略請參閱[冪等性與重試](/zh-Hant/idempotency-and-retries)。

## 疑難排解

<AccordionGroup>
  <Accordion title="缺少 Content-Type 標頭">
    所有 POST 請求必須包含 `Content-Type: application/json`。缺少時請求本文將不會被解析，API 會回傳 400 錯誤。
  </Accordion>

  <Accordion title="基礎 URL 錯誤或使用 HTTP">
    所有請求必須使用 HTTPS。請確認使用正確的環境 URL：`https://api.flexforward.com`（正式）或 `https://sandbox.flexforward.com`（開發）。
  </Accordion>

  <Accordion title="標籤 ID 的 UUID 格式無效">
    `GET /labels/{id}` 和 `GET /tracking/{id}` 的 `id` 參數必須是有效的 UUID。傳入追蹤號碼或其他識別碼格式將回傳 404 錯誤。
  </Accordion>

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