Errors

GraphQL responses use HTTP 200 for successes, application-level errors, and variables that don’t match their declared type (BAD_USER_INPUT). Inspect the errors array to know what happened. Other requests rejected before they run use other statuses, for example 429 when you exceed the request rate, and 400 with GRAPHQL_VALIDATION_FAILED when a query doesn’t match the schema or exceeds the query cost limits. A query that doesn’t parse, or is over the token limit, gets 500 with the same GRAPHQL_VALIDATION_FAILED code. That’s a rejected query, not a server fault, so don’t retry it.

Error shape

{
  "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

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

API reference

Conventions

Error shape

Domain error codes

Troubleshooting

​Error shape

​Domain error codes

​Troubleshooting

Error shape

Domain error codes

Troubleshooting