Essentials

Idempotency and retries

Networks fail. Idempotency keys let you retry any write without doing it twice.

Sending a key

Every POST needs an Idempotency-Key header, up to 255 characters. Use a fresh UUID for each new write and store it with your record of the operation, before you send the request.

curl -X POST "$NDEIPI/transfers" \
  -H "Api-Key: $NDEIPI_API_KEY" \
  -H "Idempotency-Key: 6b1f7f0e-3c55-4d1b-9a43-0d9f1c2e7a10" \
  -H "Content-Type: application/json" \
  -d '{ "source": { "type": "wallet", "wallet_id": "wal_01JA8Z4K2V9QW3H6Y7XKD2M0RS" },
        "destination": { "type": "wallet", "wallet_id": "wal_01JA8Z5B7C1DE2F3G4H5J6K7LM" },
        "amount": "25.00" }'

What the server does with it

• The same key with the same body within 24 hours returns the original status and body, with Idempotent-Replayed: true. Nothing happens twice.
• The same key with a different body returns 409 idempotency_key_reused.
• The same key while the first request is still running returns 409 idempotency_request_in_progress. Wait, then retry.
• A POST without the header returns 400 idempotency_key_missing. GET, PATCH and DELETE take no key.

When to retry

Retry connection failures, timeouts, 429 and 5xx responses, with the same idempotency key and exponential backoff with jitter. Honour Retry-After when it's present.

Don't retry other 4xx responses: the request itself needs changing. A 422 insufficient_funds will keep failing until the balance changes.