Idempotency and retries

Networks, mobile money and the internet all fail in the middle of requests. The Data Reselling API is built so you can always retry a purchase without risk of buying twice.

Your reference is the idempotency key

Every purchase needs a reference: your own unique ID, such as your order ID. Aura keeps it with the purchase and never accepts it twice.

You send	Aura returns
A new reference	201 Created and a new purchase.
A reference you used before, with the same body	200 OK and the original purchase, unchanged, with Aura-Idempotent-Replay: true. Nothing new is bought.
A reference you used before, with a different body	409 reference_conflict, with the existing purchase’s ID in details.purchase_id. Nothing is bought.

References never expire. Use one reference per intended purchase, and generate it before the first attempt so every retry carries the same one.

When to retry

What happened	Retry with the same reference?
Timeout, dropped connection or no response	Yes
429 rate_limited	Yes, after Retry-After seconds
500 internal_error	Yes, with backoff
503 network_unavailable	Yes, later, or offer another network
402 insufficient_balance	Yes, once you have topped up
Any other 4xx	No. Fix the request first

Every error says whether retrying can help in error.retryable. Back off between retries: 2, 4, 8 and 16 seconds works well, or whatever Retry-After says.

Retrying after a purchase failed

A failed purchase is final. To try again, create a new purchase with a new reference, such as your order ID with an attempt number (order-10293:2). Keep the link between the two in your own records or in metadata.

Webhooks are delivered at least once

Aura may deliver the same webhook event more than once. Each event has a unique Aura-Event-Id: record the IDs you have processed and ignore repeats. See Webhooks.