Gift card API orders fail in a handful of recurring ways, and each one needs a different response. The most important habit is separating orders that failed for certain from orders in an unknown state, because reordering a purchase that only looked failed buys the same code twice, and delivered codes are not returnable.
This field guide covers the failures you will meet in the first months of live orders, what each one means, and what to do about it.
The field guide
| Failure | What it means | What to do |
|---|---|---|
| Insufficient balance | Your prepaid account ran dry | Pause sales, top up, alert; never queue orders blind |
| Out of stock | Normal state, not an incident | Show it honestly, offer alternatives, let sync restore it |
| Region or denomination rejected | Catalogue mapping bug on your side | Fix the mapping; do not retry the same request |
| Validation error | The request itself is malformed | Fix and resend deliberately; blind retries repeat the error |
| Timeout / unknown state | The order may have completed | Look up the order or retry idempotently before reordering |
| Provider-side queue delay | Order accepted, code not yet issued | Show an honest pending state, deliver when it lands |
The failures you can trust
Insufficient balance is operational, not technical. The API is telling you your account cannot pay. Pause new sales for the affected catalogue, alert whoever tops up the balance, and resume once funds land. Letting orders pile up against an empty balance turns one alert into a queue of unhappy customers.
Out of stock deserves the least drama. Availability per product and region changes daily; treat the response as a normal outcome with a clear customer message and, where you can, a suggested alternative denomination.
Region and denomination rejections usually mean your catalogue mapping has drifted from the provider’s: you are ordering a product variant that no longer exists in that shape. Retrying changes nothing. Fix the mapping, then check your catalogue sync cadence, because a stale sync is often how the drift got there.
Validation errors are the API refusing a malformed request: a bad field, a missing parameter, an amount outside allowed bounds. Retrying blindly resends the same broken request. Log it, fix the request, add the case to your tests.
The dangerous one: timeout and unknown state
A timeout is not a failure. It is an absence of information: your request may have died on the way out, or the order may have completed and the response died on the way back. Both look identical from your side, and the second kind is the one that costs money.
Never reorder on a timeout. Resolve the state first, by one of two routes: retry the same request with the same idempotency key, which lets the provider return the original result instead of selling you a second code, or query the order status endpoint by your request reference. Only when the provider confirms the order does not exist should a new purchase go out.
Queue delays: the failure that is not one
Some orders are accepted but the code arrives later: seconds to minutes, occasionally longer. This is a pending state, not an error. Show the customer an honest “your code is on its way”, deliver by email when it lands, and let webhooks rather than polling tell you the moment it does. Storefronts that treat every slow order as a failure end up cancelling orders that were seconds from completing.
Log everything, with the provider’s error code
Every failure should leave a record: timestamp, your request ID, the provider’s error code verbatim, and the resolution. The provider’s own code matters because your daily reconciliation will one day need to explain a charge with no delivered code, or a delivery with no matching order, and the error log is where those explanations live.
Frequently asked questions
Why did my gift card order fail?
Most failures fall into six buckets: insufficient account balance, product out of stock, a region or denomination mismatch, a validation error in the request, a timeout with an unknown outcome, or a provider-side queue delay that only looks like a failure. The provider’s error code in the response tells you which bucket you are in, and each bucket has a different correct response.
Should I retry a failed gift card order?
Only some failures are retryable. Timeouts: yes, but with the same idempotency key, so a completed order is returned rather than duplicated. Out of stock and insufficient balance: retry later, once stock or funds return. Validation and mapping errors: no, fix the request first, because retrying resends the same mistake.
What does an unknown order state mean?
It means your request may or may not have completed, typically after a timeout or a dropped connection. The provider might have issued a code you never received confirmation for. Treat it as unresolved, not failed: check the order status by your request reference, or retry with the original idempotency key, and reorder only once the provider confirms nothing exists.
What do I do when the API returns insufficient balance?
Pause new sales for the affected catalogue immediately, alert whoever manages top-ups, and resume once funds land. Insufficient balance is an operational failure, not a technical one: the request was fine, the account cannot pay. Queuing orders against an empty balance turns one alert into a backlog of unhappy customers, so the pause matters as much as the top-up.
Why is my gift card order stuck in pending?
Some orders are accepted but the code is issued later, from seconds to minutes and occasionally longer, usually behind a stock check or a provider-side queue. This is a pending state, not an error. Show the customer an honest “your code is on its way”, deliver by email when it lands, and resist cancelling: storefronts that treat every slow order as failed cancel orders seconds from completing.