Errors - Jaza Docs

@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

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Customer balance is too low for this request."
  }
}

Common codes

Situation	What to do
Insufficient credits	Prompt 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.

Always pass idempotencyKey on consume so retries cannot double-charge.

⌘I