# Retries and errors

Make repeated requests predictable and uncertain outcomes recoverable.

Stage: sandbox beta. Live purchasing requires explicit activation.

## One intent, one idempotency key

Send Idempotency-Key on every mutation. Repeating the same method, path and body with the same key returns the saved result. Reusing that key with a different payload produces a conflict. Use a new key for a new intended action.

Persist your key before sending a request. If a connection fails, retry the original request with the same key. Keep the resulting order ID in your own system. The TypeScript client does not automatically retry mutations.

## Errors you can handle

Errors contain error.code, error.message, error.request_id and error.retryable. X-Request-Id is the support correlation ID. Check status and code together: 401 indicates invalid or expired credentials; 403 includes missing permission or environment gates; 409 includes idempotency conflicts; 422 includes invalid workflow state; 429 indicates throttling.

A retryable flag does not authorize a new purchase. Honour Retry-After on rate-limit responses and reuse the original idempotency key. The console shows the application's current per-minute allowance. Live access review alone does not enable headless ordering.

## Lists and catalog caching

Events, invoices, webhook endpoints and deliveries return data, next_cursor and has_more. Send the returned cursor on the next request. limit is bounded from 1 to 100. Deduplicate by resource ID.

Catalog responses support ETag and If-None-Match. Preserve catalog_version and use /v1/catalog/changes to discover changes. Pin the documented contract version and monitor the changelog when updating an integration.