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

# Errors

> How JazaError surfaces from the Node SDK, common codes, and safe retry guidance.

`@jazadev/node` throws `JazaError` with `statusCode`, `code`, and `raw` when the API rejects a call. Switch on `code` in your BFF; do not parse human messages.

## Typical envelope

```json theme={null}
{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Customer balance is too low for this request."
  }
}
```

## Common codes

| Situation            | What to do                                                                               |
| -------------------- | ---------------------------------------------------------------------------------------- |
| Insufficient credits | Prompt [top-up](/guides/top-up); do not retry the same consume until funded              |
| Unknown customer     | Verify `cus_…` id and environment (sandbox vs live)                                      |
| Unknown feature      | Confirm `featureCode` exists under **Features** in the dashboard                         |
| Auth / key issues    | Check secret key prefix (`jz_test_sk_` vs `jz_live_sk_`) and that the key is server-only |
| Rate limits / 5xx    | Retry with backoff; keep the same idempotency key on consume                             |

Exact HTTP statuses and codes can vary by endpoint — log `JazaError.raw` when debugging.

## Retry guidance

* **Safe to retry** with the **same** `idempotencyKey`: network timeouts and transient 5xx on `consume`.
* **Do not retry** unchanged when the wallet is empty or the feature code is wrong — fix the input or send the user to top up.

<Note>
  Always pass `idempotencyKey` on `consume` so retries cannot double-charge.
</Note>