> ## 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.

# Errors

> Error codes, HTTP status codes, and how to troubleshoot with request IDs.

GraphQL responses use HTTP 200 for both successes and application-level errors. Inspect the `errors` array to know what happened.

## Error shape

```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"]
    }
  ]
}
```

Error codes are namespaced by area:

* `AUTH-*` — authentication and token issues
* `BS-*` — general business / validation errors
* `GC-*` — gift card operations
* `VC-*` — virtual card operations

## Domain error codes

Fluz uses prefixed error codes so you can branch on the failing subsystem.

| Prefix      | Domain                           | Example                                                                         |
| ----------- | -------------------------------- | ------------------------------------------------------------------------------- |
| `AUTH-XXXX` | Authentication and authorization | Invalid token, missing scope                                                    |
| `VC-XXXX`   | Virtual cards                    | `VC-0025` — invalid or unsupported address                                      |
| `GC-XXXX`   | Gift cards                       | `GC-0009` — offer out of stock; `GC-0002` — amount not in allowed denominations |
| `BS-XXXX`   | Balances and settlement          | Insufficient funds, holds                                                       |

Codes not in this list surface as generic validation or server errors.

## Troubleshooting

1. **Check scope on `AUTH-*`.** These almost always mean the token was minted without the required scope; mint a new token.
2. `AUTH-0002`**Re-query before retrying `GC-*`.** Offers and stock change frequently — pull a fresh offer and retry.
3. **Re-query before retrying business errors.** `GC-0009` (stock) and similar mean the world changed — don't retry with stale**Don't retry validation errors.** `VC-*` and `BS-*` codes with `4xx`-like intent will fail identically on retry until you fix the input or balance.
4. **Retry transient server errors with backoff and jitterRetry 5xx / network errors with jitter.** Money-moving mutations are de-duplicated; see [Idempotency](/concepts/idempotency).