Reliable API requests - Ionic Docs

Reliable integrations assume that the client might not receive the response even when the server did the work.

Retry matrix

Condition	What to do
Network timeout before response	Retry with the same `Idempotency-Key`.
`409 IDEMPOTENCY_KEY_IN_PROGRESS`	Wait at least `Retry-After` seconds, then retry with the same key.
`422 IDEMPOTENCY_BODY_MISMATCH`	Stop. The retry key was reused for a different operation.
`429 RATE_LIMIT_EXCEEDED`	Back off until `Retry-After` or `X-RateLimit-Reset`.
`5xx`	Retry with the same key for creates and other money-moving mutations.
Payment declined	Do not blindly retry. Ask the buyer for another method or show the decline.

Recover after an unknown result

If a payment request times out, retrieve the resource instead of creating the payment again. Store your own order ID so you can match the API result to the original request:

Store client_reference_id on checkout sessions.
Store metadata.order_id or similar on checkout sessions, payment links, refunds, and customers.

Confirm payment on your server

Success redirects can be lost, forged, duplicated, or opened in another tab. Always verify server-side state before fulfillment.

curl https://api.ionicfi.com/v1/checkout/sessions/cs_000000000000000000000000 \
  -H "Authorization: Bearer sk_v1_test_..."

Reuse keys only for retries

An idempotency key should represent one business operation, not one endpoint forever. Good:

order_123_create_checkout_session

Bad:

checkout