Network failures happen: a timeout after you called Withdraw Funds leaves you not knowing whether the payout was created. This page covers the tools the API gives you to retry safely.
The API does not support a global Idempotency-Key header. Blindly retrying a money-moving POST can create a second transaction. Use the patterns below instead.
Payouts: check before you retry
Give every withdrawal an externalReference — a unique ID from your system. description is required alongside it:
If the request times out or errors ambiguously, look the reference up before retrying. Get Transaction accepts your externalReference in place of a transaction ID:
- Found → the payout was created; don’t resend.
404 → it never landed; safe to retry with the same reference.
This pattern does not work for NGN or mobile money payouts. Those rails must carry a
provider-formatted reference, so Rolla generates one (NG-XXXXXXXX / MM-XXXXXXXX) and your
externalReference is not stored on the transaction — looking it up afterwards always returns
404, whether or not the payout was created. Send metadata with your own id instead, and
recover by listing GET /wallet/transactions over
the window in question and matching on the metadata you attached before you resend anything. Naturally idempotent endpoints
Some creation endpoints are keyed on an identifier you supply and can be retried freely:
Webhooks: deduplicate on event_id
Webhook deliveries may arrive more than once (retries, redelivery). Every event carries a deterministic event_id — the same logical event always has the same ID — so store processed IDs and skip duplicates. See Delivery & Retries.
Retry etiquette
- Retry
5xx and network errors with exponential backoff; treat 4xx (other than 429) as terminal — fix the request instead.
- For money-moving calls, always run the lookup-then-retry pattern above rather than resending on a timer.
