Errors — JazaError codes and retry guidance - Jaza Docs

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

Typical envelope

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

Common situations

Code / situation	When it happens	What to do
Insufficient credits	Wallet balance < debit amount on `consume`	Prompt top-up; do not retry the same consume until funded
Customer not found (404)	Wrong `cus_…`, or sandbox id used with live keys (or vice versa)	Remint under the current environment; see Authentication
Unknown or inactive feature	`featureCode` missing or inactive in the dashboard	Confirm the code under Features; activate or create it
`featureCode or credits is required`	Neither `featureCode` nor `credits` sent on `consume`	Pass at least one
Invalid request / validation	Malformed body (e.g. missing `idempotencyKey`, bad `customerId`)	Fix inputs; keep the same idempotency key on retry
Auth / key issues	Bad or missing secret key	Check prefix (`jz_test_sk_` vs `jz_live_sk_`); keep secret server-only
Rate limits / 5xx	Transient platform or network errors	Retry with backoff; same idempotency key on consume

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

Consume input rules

Input	Valid?
`featureCode` only	Yes — debit dashboard `creditsCost`
`credits` only	Yes — raw debit
`featureCode` + `credits`	Yes — override amount, attribute feature
Neither	No — `featureCode or credits is required`

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.