API Rate Limits and Error Handling: A Production Readiness Checklist

Every integration meets its busiest day eventually. This checklist covers API rate limits, 429 errors, retries with backoff and caching, with real API responses to explore and a planner for your own traffic numbers.

Affiliate.com API Rate Limits and Error Handling: A Production Readiness Checklist graphic

Every integration meets its busiest day eventually: a launch, a sale, a seasonal peak or a partner that sends more traffic than planned. Pages are refreshed more often, searches pile up and a few slow minutes can turn into a wall of errors. This is a checklist for teams that already use the Affiliate.com API. It covers API rate limits, 429 and other errors, retries with backoff and caching, and every response in it is a real one, captured on November 17, 2026. You can try the errors and plan for your own traffic in the demo below.

Know your API rate limit before the traffic arrives

Your plan sets how many requests you can send in a short window, and every successful response tells you where you stand. Two headers come back on normal responses: x-ratelimit-limit is your allowance and x-ratelimit-remaining is what is left. On the test account we used, the limit was 50, but every plan sets its own, so read the number from your own responses and confirm it with your Partner Success contact. A request that fails validation (a 422) also carries x-trace-id, and the same ID appears in the body under meta.trace_id.

HeaderWhat it tells you
x-ratelimit-limitYour allowance in a short window.
x-ratelimit-remainingHow much of it is left. Log it, and slow down as it nears zero.
x-trace-idAn ID for this exact request, present on validation errors as well as normal responses. Send it to support when something looks wrong.

Two responses leave the headers out. A request with a wrong key returns 401 without them, and so does a refused request, described next. Do not rely on the headers being present.

What a 429 Too Many Requests response looks like

When too many requests arrive at once, the API answers 429 with a short message instead of a result: {"message":"HTTP Error.","error":"Too Many Attempts."}. We tested it with a burst of 80 simultaneous requests on one account. 53 succeeded and 27 were refused. The allowance came back within half a second, so a short pause is usually all a refused request needs.

Notice what the refused response does not contain. There is no Retry-After header, so your code has to choose how long to wait. That is the main reason to have a retry plan before a busy period and not during it.

See real errors and plan for traffic

The demo has two tabs. The error explorer shows eight real responses with the request that caused each one, the headers that came back and what to do next. The backoff planner takes your own limit and your expected peak, and works out how much of the traffic a cache has to absorb and how long to wait between retries. The responses were captured on November 17, 2026.

The pattern across the errors is simple. Anything that is your request or your key being wrong should be fixed and not retried. Only a refused request is worth sending again, and only after a wait.

Which errors to retry

What you seeRetry?What to do
429 Too Many AttemptsYes, after a waitBack off with random jitter, slow your sending and show cached data meanwhile.
422 Validation failedNoThe body names the field or value that is wrong. Fix the request. A retry returns the same error.
401 UnauthenticatedNoCheck the key and that it is sent as a Bearer token. A retry will not help.
5xx Server errorA few timesWe did not produce one in our tests. Treat it as temporary: retry with backoff, then fall back.
A timeout or dropped connectionA few timesUse the same backoff, and set your own timeout so a slow call cannot hold up a page.

Retry with exponential backoff and jitter

A naive retry can make a busy period worse. If every client waits the same second and then retries together, they arrive together again. Two things prevent that. Double the wait after each failure, up to a ceiling, and make the wait random, so retries spread out. Give up after a few tries and show a fallback, such as the last good result with its time.

async function callWithRetry(send, maxTries = 4) {
  for (let attempt = 0; attempt < maxTries; attempt++) {
    const res = await send();
    if (res.ok) return res;
    // 4xx other than 429 means the request or key is wrong: retrying cannot help
    if (res.status !== 429 && res.status < 500) throw new Error(`HTTP ${res.status}`);
    // wait a random time up to a ceiling that doubles each try (250 ms, 500 ms, 1 s ... 8 s)
    const ceiling = Math.min(8000, 250 * 2 ** attempt);
    await new Promise((r) => setTimeout(r, Math.random() * ceiling));
  }
  throw new Error("still failing after retries: show your fallback");
}

Cache API responses that do not change by the second

The cheapest request is the one you do not send. Product data does not change every second. In checks on November 12, 2026, between 73 and 99 of every 100 sampled product records had been updated within the previous 24 hours, depending on the category, and at least 88 of 100 within seven days. That makes a cache of minutes to hours safe for most pages. Our guide on how often product pages should be updated covers the reasoning.

WhatHow long to keep itWhy
Search results for a popular pageMinutes to an hourThe same page is requested over and over, and the results rarely change within the hour.
Price history for a productA few hoursIts history is built from daily data, so most of it changes once a day.
A barcode lookupA day or moreA link or an identifier maps to the same product.
An error responseDo not cacheA cached error keeps failing after the cause is gone.

Check what your agreement allows for storing product data before you set long lifetimes, and show the time you fetched a price so a reader can see how fresh it is. One more habit matters at peak: when a cache entry expires, many requests can ask for it at once. The pattern below shares one request between all of them.

const cache = new Map();      // key -> { value, expires }
const inFlight = new Map();   // key -> Promise, so one slow call is shared

async function cached(key, ttlMs, load) {
  const hit = cache.get(key);
  if (hit && hit.expires > Date.now()) return hit.value;
  if (inFlight.has(key)) return inFlight.get(key);   // many callers, one request
  const p = load().then((value) => {
    cache.set(key, { value, expires: Date.now() + ttlMs });
    return value;
  }).finally(() => inFlight.delete(key));
  inFlight.set(key, p);
  return p;
}

Spread the load and cap your concurrency

Most spikes are made of requests that could have been sent earlier or later. Warm the cache for your busiest pages before a known peak begins, and schedule bulk jobs away from your peak hours. Put a cap on how many requests your own code sends at once, so a burst on your side does not become a burst on ours. Fetch only the fields you use with fields, and ask for per_page up to its maximum of 100 and not many small pages. For seasonal peaks such as Black Friday, the Black Friday Deals API guide and planning holiday content with product data go through what to check.

Fail gracefully

Decide now what a visitor sees when data cannot be fetched. The best answer is usually the last good result with the time it was fetched. A sold-out or missing product is a separate case, covered in handling out-of-stock and price-changed offers. In both cases, a page that explains itself keeps trust better than one that shows a blank space.

Log trace IDs and error rates

When something goes wrong at peak, the first question is which request it was. Log the status and the endpoint for every error, the trace ID whenever the response has one, and the remaining allowance when it gets low. With those, support can find the exact request in minutes. Also watch the share of your requests that return an error status, because a rise in that share is the earliest warning you will get.

Check your API usage

Your account shows how much you have used. If you work through the MCP server, the get-account-usage tool returns usage by tool, and in our test calling it was not counted as billable. Check it before a peak, and again afterward, so you know what a busy period looks like for your account. MCP or REST explains the two ways of connecting.

The production readiness checklist

Before a traffic peakDone when
Confirm your limitYou have read x-ratelimit-limit from a live response and confirmed it with Partner Success.
Estimate your peakYou know your expected requests per second, not only per day.
Handle 429 properlyRefused requests are retried with a growing, random wait.
Never retry a 422 or a 401Your code fixes or reports those errors instead of looping.
Cache the hot pagesPopular searches and price histories are served from a cache with a sensible lifetime.
Share one request between callersAn expired cache entry triggers one request, not hundreds.
Cap your own concurrencyYour code never sends more than a set number of requests at once.
Warm the cache aheadYour busiest pages are loaded before a known peak, such as a sale, starts.
Plan the fallbackA failed fetch shows the last good data with its time.
Log trace IDsEvery error you record includes its trace ID when the response has one.

If something looks wrong

If you are not sure of your limit, or you would like a second pair of eyes on your retry and caching setup before a peak, our team is glad to look. Include the trace ID of any request you are asking about. Schedule a call with our team.