Errors, retries, idempotency

Payments are inherently asynchronous. Networks, providers, and third-party integrations can fail transiently. Your integration should be resilient and safe to retry.

Retries

• Retry transient failures (timeouts, 429, some 5xx) with exponential backoff.
• Do not blindly retry non-idempotent create/init endpoints unless you have a safe idempotency key strategy.

Idempotency

For endpoints that create resources (like checkout sessions), send a unique key derived from your order ID so repeated calls do not create duplicates. If the API provides a dedicated idempotency header or field, prefer that mechanism.

Observability

• Log request/response metadata and business references (session ID, invoice ID, tx hash).
• Capture error bodies in server logs; they often contain actionable details.

Next: browse endpoint details in API Reference.