---
title: Gift Card API Rate Limits and Partial Failures
description: A practical guide to gift card API rate limiting, partial failures in bulk reward orders, and retry strategies that avoid double payouts.
image: https://www.wincubeglobal.com/hubfs/blog-images/bulk-gift-card-api-rate-limits-partial-failures-thumbnail.png
---

[Skip to content](https://www.wincubeglobal.com/handling-rate-limits-and-partial-failures-in-bulk-gift-card-api-orders#main-content)

![Thumbnail: three payout lanes with the headline Rate Limits and Partial Failures](https://www.wincubeglobal.com/hs-fs/hubfs/blog-images/bulk-gift-card-api-rate-limits-partial-failures-thumbnail.png?width=1600&height=900&name=bulk-gift-card-api-rate-limits-partial-failures-thumbnail.png)

Digital Gift Cards WINK WINCUBE

# Handling Rate Limits and Partial Failures in Bulk Gift Card API Orders

![Doa Lee](https://7528315.fs1.hubspotusercontent-na1.net/hub/7528315/hubfs/raw_assets/public/mV0_d-cms-elevate-theme_hubspot/elevate/images/avatar-placeholder.jpg?width=48&height=48&name=avatar-placeholder.jpg)

 Doa Lee

November 18, 2026

When your platform sends thousands of rewards in one run, two things will eventually happen. The gift card API will push back with rate limits, and some items in a large order will succeed while others fail. The hard part is not catching those errors. It is recovering from them without double-paying a recipient or silently dropping one. This guide covers how engineering and platform teams can design for throttling and partly failed batches from the start.

**In short:** Treat rate limits as normal traffic shaping. Use exponential backoff with jitter, respect any retry hints the API returns, and break large orders into chunks that stay under the published limits. For partial failures, track status per item rather than per batch, reconcile against the provider's records before you retry anything, and resend only the failed items using stable idempotency keys so a retried request cannot create a second payout.

APIs now carry a large share of the web's workload. That raises the stakes for how client systems behave under load. Cloudflare reported that APIs account for 57% of dynamic internet traffic around the globe ([Cloudflare](https://www.cloudflare.com/press-releases/2024/new-cloudflare-report-shows-organizations-struggle-to-identify-and-manage), *2024 API Security and Management Report*, 2024). When that much traffic is machine-to-machine, providers protect shared infrastructure with throttling, and well-behaved clients are expected to slow down instead of hammering an endpoint.

APIs are also increasingly tied to revenue, which makes reliability a business concern as well as an engineering one. Postman's 2025 State of the API Report, based on a survey of 5,700 respondents, found that 65% of organizations that use APIs are generating revenue from them ([Nordic APIs](https://nordicapis.com/a-deep-dive-into-the-state-of-the-api-2025/), *A Deep Dive Into the State of the API 2025*, 2025). For reward programs, a failed or duplicated payout carries a direct cost and erodes recipient trust, so resilience patterns belong in the core design.

## Designing Around Gift Card API Rate Limits

Rate limits usually show up as HTTP 429 responses, sometimes with a \`Retry-After\` header or a similar hint saying when to try again. Some providers also return headers that report your remaining quota for the current window. The first rule is simple: read and follow those signals before you apply any logic of your own.

### Backoff with jitter

When a request is throttled, wait before retrying, and lengthen the wait after each consecutive failure. Plain exponential backoff has a known weakness. If many workers get throttled at the same moment, they all retry on the same schedule and collide again. Marc Brooker, writing on the AWS Architecture Blog, made the point directly: "The solution isn't to remove backoff. It's to add jitter" ([AWS Architecture Blog](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/), *Exponential Backoff And Jitter*, 2015). Randomizing the delay spreads retries out so the provider sees a smoother load.

A practical retry policy for a reward API usually includes:

- A base delay and a maximum delay cap, so waits do not grow without limit
- Random jitter applied to each computed delay
- A maximum retry count, after which the item moves to a failed or review state
- Retries only for errors that can be retried, such as 429, 503 and network timeouts, and never for validation errors like an invalid product code or bad recipient data

![Table of which gift card API failures to retry (429, 503, timeouts) and which not to (validation errors)](https://www.wincubeglobal.com/hs-fs/hubfs/blog-images/which-gift-card-api-errors-to-retry.png?width=2400&height=1350&name=which-gift-card-api-errors-to-retry.png)

### Chunking large orders

Instead of sending one huge request or firing thousands of single-item calls in parallel, split bulk orders into chunks sized to the provider's documented limits. A client-side token bucket or leaky bucket limiter keeps your outbound rate below the ceiling, so fewer requests get throttled in the first place. Chunking also limits the damage when something fails: a failed chunk of 100 items is far easier to reconcile than a failed request of 10,000.

If you are still choosing between sending rewards in batches or one at a time, our overview of [what a bulk gift card API is and why platforms are adopting one](https://www.wincubeglobal.com/what-is-a-bulk-gift-card-api-and-why-platforms-are-adopting-one) covers the architectural trade-offs.

## Handling Partial Failures in Bulk Reward Orders

A partial failure happens when a bulk order is accepted but its line items end in different states. Some codes are issued, some are rejected because a product is out of stock or a value is unsupported in a region, and some are still pending. The most common mistake is treating the batch as one unit, either retrying all of it (which risks duplicates) or marking all of it failed (which hides the items that actually went out).

### Track status per item

Give every reward its own record in your system with a unique internal ID, the batch it belongs to, and a clear state machine. A typical set of states:

- **Queued:** created internally, not yet sent
- **Submitted:** sent to the provider, no final response yet
- **Fulfilled:** a code or delivery confirmation was received
- **Failed (retryable):** a temporary error, eligible for another attempt
- **Failed (terminal):** a permanent error that needs a fix to the data or a product swap
- **Unknown:** the request may or may not have been processed, for example after a timeout

The "unknown" state matters most. A timeout does not mean the order failed. The provider may have processed it and the response was lost on the way back.

### Reconcile before you retry

Before resubmitting anything in the unknown or submitted state, ask the provider what actually happened. Use an order status endpoint, a transaction lookup by your reference ID, or webhook events if the API supports them. Then compare the provider's view with your own records item by item. Only items the provider confirms as not processed, or as failed with a retryable error, should move back into the send queue.

Many teams run this reconciliation in two places: inline right after a batch completes, and as a scheduled job that sweeps for items stuck in submitted or unknown beyond a set threshold.

## A Retry Strategy That Avoids Double Payouts

Even careful reconciliation leaves race conditions, which is why idempotency is the backstop. Attach a stable idempotency key to every reward item, derived from your internal reward ID rather than generated fresh on each attempt. If the provider receives the same key twice, it should return the original result instead of issuing a second gift card.

A few practical rules help here:

- Generate the key once, when the reward record is created, and store it with the record
- Reuse the same key on every retry of that item, including retries that go out in a different chunk
- Never reuse a key for a different recipient, amount or product, since that can return a stale result for a new request
- Confirm how long the provider keeps idempotency keys, and make sure your retry windows fall inside that period

![Five habits to retry gift card API orders without double payouts: back off, chunk, track, reconcile, reuse the key](https://www.wincubeglobal.com/hs-fs/hubfs/blog-images/retry-gift-card-api-orders-without-double-payouts.png?width=2400&height=1350&name=retry-gift-card-api-orders-without-double-payouts.png)

Pair idempotency with clear alerting. Items that reach the terminal failure state or hit the maximum retry count should surface to an operations queue with enough context, such as error code, product and recipient region, for a person to decide whether to swap the product, fix the data or cancel the reward. Automated retries should handle temporary problems, and people should handle the permanent ones.

Finally, test these paths on purpose. Use a sandbox environment to simulate 429 responses, timeouts and mixed-result batches before going live, and confirm that your reconciliation and idempotency logic produce exactly one payout per reward under each scenario.

## Where Wincube Global Fits

Wincube Global provides reward infrastructure for platforms that send gift cards at volume. Wincube Global has processed over USD 220 million in gift card GMV in 2025 across a catalog of more than 30,000 gift cards spanning over 90 countries. At high volume, item-level status, reconciliation and safe resubmission are basic requirements for any team running reward payouts, not optional extras.

If your team is planning a bulk reward integration or reworking how it handles throttling and partly failed orders, it helps to map out your retry and reconciliation flow early, before volumes grow. If this is relevant to your team, [**Contact Us**](https://www.wincubeglobal.com/?utm_source=blog&utm_medium=cta&utm_campaign=handling-rate-limits-and-partial-failures-in-bulk-gift-card-api-orders#hs_form_target_widget_1783922531344) and we can walk through what it would look like.

## FAQ

### What should my system do when a gift card API returns a 429 error?

Pause and retry later using exponential backoff with random jitter, and follow any \`Retry-After\` or quota headers the API provides. Set a maximum retry count so a throttled item eventually moves to a review state instead of retrying forever.

### How do I know which items in a bulk reward order actually succeeded?

Track every reward as its own record with an item-level status, then reconcile against the provider's order or transaction status endpoint, or its webhook events. Don't infer item outcomes from the batch-level response alone, especially after a timeout.

### How can I retry failed rewards without paying a recipient twice?

Give each reward a stable idempotency key when it is created and reuse that same key on every retry. Combined with reconciling before you resubmit, this means the provider returns the original result for a duplicate request instead of issuing a second gift card.

---

**Sources**

- Cloudflare, *2024 API Security and Management Report (press release)*, retrieved 2026-11-18, https://www.cloudflare.com/press-releases/2024/new-cloudflare-report-shows-organizations-struggle-to-identify-and-manage
- Nordic APIs, *A Deep Dive Into the State of the API 2025*, retrieved 2026-11-18, https://nordicapis.com/a-deep-dive-into-the-state-of-the-api-2025/
- AWS Architecture Blog, *Exponential Backoff And Jitter*, retrieved 2026-11-18, https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/

[Blog Home](https://www.wincubeglobal.com/?utm_source=blog&utm_medium=home_button&utm_campaign=handling-rate-limits-and-partial-failures-in-bulk-gift-card-api-orders)

 

## Share this post

<https://www.facebook.com/sharer/sharer.php?u=https%3A%2F%2Fwww.wincubeglobal.com%2Fhandling-rate-limits-and-partial-failures-in-bulk-gift-card-api-orders><https://twitter.com/intent/tweet?url=https%3A%2F%2Fwww.wincubeglobal.com%2Fhandling-rate-limits-and-partial-failures-in-bulk-gift-card-api-orders><https://www.linkedin.com/shareArticle?mini=true&url=https%3A%2F%2Fwww.wincubeglobal.com%2Fhandling-rate-limits-and-partial-failures-in-bulk-gift-card-api-orders><https://pinterest.com/pin/create/button/?url=https%3A%2F%2Fwww.wincubeglobal.com%2Fhandling-rate-limits-and-partial-failures-in-bulk-gift-card-api-orders>[mailto:https%3A%2F%2Fwww.wincubeglobal.com%2Fhandling-rate-limits-and-partial-failures-in-bulk-gift-card-api-orders](mailto:https%3A%2F%2Fwww.wincubeglobal.com%2Fhandling-rate-limits-and-partial-failures-in-bulk-gift-card-api-orders)

## Keep reading

### [![Thumbnail: globe centered on Europe with the headline Bank Transfer or Gift Card for EU Payouts](https://www.wincubeglobal.com/hs-fs/hubfs/blog-images/eu-reward-payouts-bank-transfer-vs-gift-card-thumbnail.png?width=1600&height=900&name=eu-reward-payouts-bank-transfer-vs-gift-card-thumbnail.png) Digital Gift Cards WINK WINCUBE Bank Transfers vs Gift Cards for EU Reward Payouts](https://www.wincubeglobal.com/bank-transfers-vs-digital-gift-cards-for-eu-reward-payouts-after-verification-of-payee)

### [![Thumbnail: a ruffled lucky pouch with gift cards peeking out and a calendar badge, for Seollal gift card planning in Korea](https://www.wincubeglobal.com/hs-fs/hubfs/blog-images/seollal-gift-card-planning-korea-based-teams-thumbnail.png?width=1600&height=900&name=seollal-gift-card-planning-korea-based-teams-thumbnail.png) Digital Gift Cards WINK WINCUBE Seollal 2027 Gift Card Planning for Korea-Based Teams](https://www.wincubeglobal.com/planning-seollal-gifts-for-korea-based-teams-and-clients-what-global-hr-and-procurement-need-to-know-about-lunar-new-year-gift-card-programs)

[![2-1](https://www.wincubeglobal.com/hs-fs/hubfs/2-1.png?width=360&height=120&name=2-1.png "2-1")](https://www.wincubeglobal.com/)

[![logo-1](https://www.wincubeglobal.com/hs-fs/hubfs/logo-1.png?width=283&height=100&name=logo-1.png "logo-1")](https://wincubemkt.com/)

---

 Copyright ⓒ 2026 Wincube Marketing Co., Ltd. 

```json
{
  "@context" : "https://schema.org",
  "@type" : "BlogPosting",
  "author" : {
    "@type" : "Person",
    "name" : "Doa Lee",
    "url" : "https://www.wincubeglobal.com/author/doa-lee"
  },
  "dateModified" : "2026-11-18T06:40:13.336Z",
  "datePublished" : "2026-11-18T06:40:13.000Z",
  "headline" : "Gift Card API Rate Limits and Partial Failures",
  "image" : [ "https://www.wincubeglobal.com/hubfs/blog-images/bulk-gift-card-api-rate-limits-partial-failures-thumbnail.png" ],
  "mainEntityOfPage" : {
    "@id" : "https://www.wincubeglobal.com/handling-rate-limits-and-partial-failures-in-bulk-gift-card-api-orders",
    "@type" : "WebPage"
  },
  "publisher" : {
    "@type" : "Organization",
    "logo" : {
      "@type" : "ImageObject",
      "url" : "https://www.wincubeglobal.com/hubfs/1-1.png"
    }
  }
}
```

```json
{
  "@context" : "https://schema.org",
  "@id" : "https://www.wincubeglobal.com/#org",
  "@type" : "Organization",
  "address" : {
    "@type" : "PostalAddress",
    "addressCountry" : "KR",
    "addressLocality" : "Seoul"
  },
  "alternateName" : [ "Wincube Global", "WINCUBE", "Wincube" ],
  "areaServed" : [ {
    "@type" : "Country",
    "name" : "Taiwan"
  }, {
    "@type" : "Country",
    "name" : "Japan"
  }, {
    "@type" : "Country",
    "name" : "United States"
  }, {
    "@type" : "Country",
    "name" : "Canada"
  }, {
    "@type" : "Country",
    "name" : "South Korea"
  }, {
    "@type" : "Place",
    "name" : "Europe"
  } ],
  "description" : "Wincube is a B2B digital gift card aggregator and rewards infrastructure provider headquartered in Seoul, South Korea, with a U.S. branch in Delaware. It is strong in Taiwan, Japan, the United States, Canada, South Korea and Europe, with gift card coverage in 90+ countries.",
  "foundingDate" : "2011",
  "legalName" : "Wincube Marketing Co., Ltd.",
  "logo" : "https://www.wincubeglobal.com/hubfs/logo-1.png",
  "name" : "Wincube Marketing",
  "sameAs" : [ "https://wincubemkt.com/", "https://www.linkedin.com/showcase/143064148" ],
  "subOrganization" : {
    "@type" : "Organization",
    "address" : {
      "@type" : "PostalAddress",
      "addressCountry" : "US",
      "addressRegion" : "Delaware"
    },
    "name" : "Wincube Inc."
  },
  "url" : "https://www.wincubeglobal.com"
}
```

```json
{
  "@context" : "https://schema.org",
  "@id" : "https://www.wincubeglobal.com/#blog",
  "@type" : "Blog",
  "alternateName" : "WINK by Wincube Global",
  "name" : "WINK",
  "publisher" : {
    "@id" : "https://www.wincubeglobal.com/#org"
  },
  "url" : "https://www.wincubeglobal.com/"
}
```

```json
{
  "@context" : "https://schema.org",
  "@id" : "https://www.wincubeglobal.com/#hschang",
  "@type" : "Person",
  "alternateName" : "Hyung Soon Chang",
  "jobTitle" : "Chief Business Development Officer",
  "name" : "HS Chang",
  "sameAs" : [ "https://www.linkedin.com/in/hyung-soon-chang-19b1a926/" ],
  "url" : "https://www.wincubeglobal.com/author/hs-chang",
  "worksFor" : {
    "@id" : "https://www.wincubeglobal.com/#org"
  }
}
```

```json
{
  "@context" : "https://schema.org",
  "@id" : "https://www.wincubeglobal.com/author/hs-chang#page",
  "@type" : "ProfilePage",
  "mainEntity" : {
    "@id" : "https://www.wincubeglobal.com/#hschang"
  },
  "url" : "https://www.wincubeglobal.com/author/hs-chang"
}
```