Errors and retries

Handle errors using the HTTP status and error field. Only retry when the failure is transient.

Error format

Errors use a stable JSON object with error for programmatic handling and message for readable context. Missing and out-of-scope resources deliberately return the same response.

{
  "error": "not_found",
  "message": "Recurso não encontrado."
}

HTTP statuses

400

400 — invalid request or filter, such as an unsupported status.

Do not retry

401

401 — missing, invalid or revoked code, or an incorrectly formatted header.

Do not retry

403

403 — the Stripe installation associated with the code is no longer active.

Do not retry

404

404 — customer, invoice or PDF unavailable in this scope; this response prevents cross-account enumeration.

Do not retry

429

429 — temporary request limit; wait before attempting the request again.

Retry

502/503

502/503 — Stripe or InvoiceXpress is temporarily unavailable; retry with backoff.

Retry

Retry policy

Use bounded retries with exponential backoff and jitter to avoid amplifying upstream failures.

Only retry 429, 502 and 503 unless the contract explicitly says otherwise.
Start with a short delay and increase it exponentially between attempts.
Add jitter, cap the number of attempts and define a timeout per request.
Do not retry 400, 401, 403 or 404 without fixing the request, credentials or scope.