Retries and errors
Make repeated requests predictable and uncertain outcomes recoverable.
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.