> ## Documentation Index
> Fetch the complete documentation index at: /llms.txt
> Use this file to discover all available pages before exploring further.

# Retry Strategy

> Handle temporary errors and maximize payment success rates with exponential backoff.

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

<CardGroup cols={3}>
  <Card title="Retry (5xx)" icon="arrows-rotate">
    `500`, `502`, `503`, `504` — Server errors are usually temporary.
  </Card>

  <Card title="Retry with caution (429)" icon="clock">
    `429 Too Many Requests` — Respect the `Retry-After` header.
  </Card>

  <Card title="Do NOT retry (4xx)" icon="ban">
    `400`, `401`, `403`, `404`, `422` — Client errors won't resolve with retries.
  </Card>
</CardGroup>

## 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

```bash
# 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

```bash
# 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

<Card title="Idempotency Guide" icon="key" href="/en/core-concepts/security/idempotency">
  Learn how idempotency keys prevent duplicate transactions during retries.
</Card>