The reference, and retrying safely

Your reference is the only thing standing between a timeout and a double charge.

Every order carries a reference you choose. We claim it against a unique index before anything is charged, so two orders can never share one. The second request does not create anything: it returns the first order, with a 200 and "This reference was already used. Returning the original order."

This is what makes the API safe to retry. It is also the only thing that does.

Choosing one

  • Unique across your own orders, forever. Not just within a day.
  • 120 characters or fewer.
  • Something you can find again in your own records.
  • Generated before you send the request, and stored with the order you are about to place.

A UUID works. So does alpha-2026-11-18-000147. What matters is that you can reproduce it, because a retry has to send the same one.

Warning

Never generate a new reference for a retry. That is not a retry, it is a second order, and your customer pays twice. If your code generates the reference inside the function that sends the request, it is already wrong.

Which failures are safe to retry

What you gotDid the order happen?Do this
202yesnothing. Poll, or wait for the webhook.
200 with the "already used" messageyes, earliernothing.
422 from validation, data is nullnofix the request. The reference is free.
422 with the order in datayes, and it failedread data.state. Do not retry.
429nolet your open requests finish, then retry, same reference.
503unknownretry with the same reference, or poll it.
A timeout, no response at allunknownretry with the same reference, or poll it.
401, 403nofix the credential. Retrying changes nothing.

The two "unknown" rows are the ones that matter. Both have the same safe answer, and it is the same answer either way.

Recovering from a timeout

Your request timed out. You do not know whether we got it.

Option one, retry. Send the identical request again, same reference. If the first attempt landed you get the original order back with a 200 and nothing is charged twice. If it did not land, this one goes through normally.

Option two, ask. Call Get an order with that reference.

Did it land?bash
curl https://stagingapi.getelectric.ng/api/v2/reseller/orders/alpha-000147 \
  -H 'Authorization: Bearer <your-key>'

A 404 with "No order with that reference." is the one response that tells you nothing was created and the reference is still free to use. Anything else means the order exists, and its state tells you where it got to.

Tip

Polling is the better habit of the two. A retry re-sends the whole body and is counted against your in-flight budget as a purchase; a poll is a cheap read. Retry when you want the result in the same request, poll when you are reconciling afterwards.

Reconciling in bulk

To check a batch, List orders pages through your orders newest first. For anything older than a page or two, keep your own record keyed by your reference and ask about the ones you are unsure of. There is no bulk lookup by a list of references.

What the reference is not

It is not a transaction id. We generate our own, and it appears as transaction on the order once there is one. Use ours when talking to us about money, and yours to find your own records.