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

# 錯誤

> 錯誤代碼、HTTP 狀態碼，以及如何使用 request ID 進行疑難排解。

GraphQL 回應在成功與應用層錯誤皆使用 HTTP 200。請檢查 `errors` 陣列以了解發生了什麼事。

## 錯誤結構

```json theme={null}
{
  "errors": [
    {
      "message": "Offer out of stock",
      "extensions": {
        "code": "GC-0009",
        "path": ["purchaseGiftCard"],
        "requestId": "req_01H...Offer out of stock",
      "code": "GC-0009",
      "path": ["purchaseGiftCard"]
    }
  ]
}
```

錯誤代碼依領域命名空間區分：

* `AUTH-*` — 驗證與權杖問題
* `BS-*` — 一般商務 / 驗證錯誤
* `GC-*` — 禮品卡操作
* `VC-*` — 虛擬卡操作

## 網域錯誤代碼

Fluz 使用帶前綴的錯誤代碼，方便你依失敗的子系統進行分支處理。

| Prefix      | Domain  | Example                                 |
| ----------- | ------- | --------------------------------------- |
| `AUTH-XXXX` | 身分驗證與授權 | 無效權杖、缺少 scope                           |
| `VC-XXXX`   | 虛擬卡     | `VC-0025` — 無效或不支援的地址                   |
| `GC-XXXX`   | 禮品卡     | `GC-0009` — 商品缺貨；`GC-0002` — 金額不在允許的面額中 |
| `BS-XXXX`   | 餘額與清算   | 餘額不足、預扣款                                |

不在此清單中的代碼會以一般驗證或伺服器錯誤呈現。

## 疑難排解

1. 檢查 `AUTH-*` 的 scope。這幾乎都表示權杖在簽發時缺少必要的 scope；請重新簽發新的權杖。
2. `AUTH-0002`重新查詢後再重試 `GC-*`。優惠與庫存變動頻繁 — 先拉取最新的優惠再重試。
3. 重新查詢後再重試商務錯誤。`GC-0009`（庫存）與類似情況表示狀態已變更 — 請勿使用過時資料重試。不要重試驗證錯誤。具有類 `4xx`意圖的 `VC-*` 與 `BS-*` 代碼會在未修正輸入或餘額前持續失敗。
4. 以退避與隨機抖動重試暫時性伺服器錯誤。對 5xx / 網路錯誤使用抖動策略重試。金流類變更操作具去重處理；請參見 [Idempotency](/concepts/idempotency)。