Network timeouts, provider outages, and rate limits are common in payment systems. A well-designed retry strategy maximizes your success rate without overloading the system.

​
When to retry

Retry (5xx)

500, 502, 503, 504 — Server errors are usually temporary.

Retry with caution (429)

429 Too Many Requests — Respect the Retry-After header.

Do NOT retry (4xx)

400, 401, 403, 404, 422 — Client errors won’t resolve with retries.

​
Exponential backoff

Increase the delay between retries progressively to give the system time to recover:
AttemptDelayTotal elapsed
1st retry1 second1s
2nd retry2 seconds3s
3rd retry4 seconds7s
4th retry8 seconds15s

​
Implementation

# Pseudocode for retry with exponential backoff
#
# For each attempt (1 to max_retries):
#   1. Send the request with Idempotency-Key header
#   2. If success (2xx) → done
#   3. If client error (4xx except 429) → stop, don't retry
#   4. If 429 → wait Retry-After seconds, then retry
#   5. If server error (5xx) → wait (2^attempt) seconds + random jitter, then retry

​
Complete example: payment with retry + idempotency

# Create a payment with idempotency key for safe retries
IDEMPOTENCY_KEY=$(uuidgen)

curl -X POST https://api.simiz.io/v1/transactions \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "amount": 5000,
    "currency": "XAF",
    "payment_method": "ORANGE_MONEY",
    "payer": { "phone": "237690000000", "name": "John Doe" },
    "description": "Order #12345"
  }'

# If the request fails with 5xx, retry with the SAME idempotency key.
# The server guarantees the transaction is created only once.

​
Best practices

  1. Always combine with idempotency — Use the Idempotency-Key header to prevent duplicate transactions on retries
  2. Limit retries — 3–5 retries is sufficient. Beyond that, the error is likely permanent
  3. Add jitter — Random variation prevents all clients from retrying at the same time
  4. Respect Retry-After — If the header is present, use its value instead of your calculated delay
  5. Log all retries — Keep audit logs for debugging and monitoring

Idempotency Guide

Learn how idempotency keys prevent duplicate transactions during retries.