Retry Strategy

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:

Attempt	Delay	Total elapsed
1st retry	1 second	1s
2nd retry	2 seconds	3s
3rd retry	4 seconds	7s
4th retry	8 seconds	15s

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

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

Idempotency Guide

Learn how idempotency keys prevent duplicate transactions during retries.

Getting Started

Core Concepts

Billing

Guides

When to retry

Retry (5xx)

Retry with caution (429)

Do NOT retry (4xx)

Exponential backoff

Implementation

Complete example: payment with retry + idempotency

Best practices

Idempotency Guide

​When to retry

Retry (5xx)

Retry with caution (429)

Do NOT retry (4xx)

​Exponential backoff

​Implementation

​Complete example: payment with retry + idempotency

​Best practices

Idempotency Guide

When to retry

Exponential backoff

Implementation

Complete example: payment with retry + idempotency

Best practices