Reliable API requests

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. A `502 GATEWAY_ERROR` from confirming a payment or creating a refund means no money moved: retry with a new key.
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

What’s next

Test cards

See the card numbers and behaviors that test mode supports.

Idempotency

Retry a request without repeating its effect.

Errors

Read the error envelope and what each status code means.

Decline codes

Look up what each card decline means and whether the same card can succeed later.

Start here

Key concepts

Test and go live

Reliable API requests

Retry matrix

Recover after an unknown result

Confirm payment on your server

Reuse keys only for retries

What’s next

Test cards

Idempotency

Errors

Decline codes

​Retry matrix

​Recover after an unknown result

​Confirm payment on your server

​Reuse keys only for retries

​What’s next

Test cards

Idempotency

Errors

Decline codes

Retry matrix

Recover after an unknown result

Confirm payment on your server

Reuse keys only for retries

What’s next