> ## 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 状态码，以及如何使用请求 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 / 网络错误使用抖动重试。** 涉及资金流动的变更具备去重能力；参见 [幂等性](/concepts/idempotency)。