Handling API Rate Limits in Production (429s and X-RateLimit Headers)

Generic rate-limit handling code, written against the pattern most APIs use, will mostly work against AIOZ Stream's API. Mostly, not fully: one of its three rate-limit headers is named and shaped differently from the convention most developers have already internalized from GitHub, Zendesk, and similar APIs, and missing that difference is exactly the kind of bug that only shows up once real traffic hits a limit in production.

TL;DR:

• AIOZ Stream's documented limits: 100 requests per minute for uploads, 200 for writes, 500 for reads, three separate budgets, not one shared limit across every call.
• Every response carries three headers: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Retry-After, the last one named differently from the more common X-RateLimit-Reset pattern other APIs use.
• X-RateLimit-Retry-After gives seconds remaining until the window resets, not a Unix timestamp, the format difference that actually matters if code was written expecting the more common convention.
• A 429 response includes a specific message format, "Too many requests. Please wait X seconds before retrying," and the same Retry-After value client code should already be tracking proactively.
• When an API tells you exactly how long to wait, using that number directly beats a guessed exponential backoff, backoff strategies exist for when a server doesn't give you a precise answer, and AIOZ does.

AIOZ Stream's actual limits

Three separate budgets, not one shared pool: uploads are capped at 100 requests per minute, writes at 200, and reads at 500. That split matters for how a real integration should think about its own request budget, a bulk operation hammering the read endpoints to list or check on videos has far more headroom than an upload-heavy workflow, and treating all API calls as drawing from one combined limit would badly underestimate what's actually available for read-style operations specifically.

Three headers, and one that's not what you'd expect

Every API response carries three headers, verified directly against AIOZ's own documentation: X-RateLimit-Limit, described as showing "the applied request limit per minute," and X-RateLimit-Remaining, "the number of available requests you have left for the current time window," both of which behave exactly the way anyone who's integrated a rate-limited API before would expect. The third one is where AIOZ's naming actually diverges from the more common pattern: X-RateLimit-Retry-After, not the X-RateLimit-Reset name GitHub, Zendesk, and several other major APIs use for the equivalent concept. The value's shape differs too, not just the name, AIOZ's documentation describes it as showing "the number of seconds left until the current rate limit window resets," a countdown in seconds, while the more common X-RateLimit-Reset convention typically returns a Unix epoch timestamp, an absolute point in time rather than a relative countdown. Code written to parse an absolute timestamp out of a header by that more common name will silently fail to find it here, and code that does find X-RateLimit-Retry-After but assumes it's a timestamp rather than a seconds-remaining count will compute a nonsensical wait time. Worth noting AIOZ isn't inventing something unusual out of nowhere here either, header naming for rate limits was never formally standardized until fairly recently. The IETF's own draft-polli-ratelimit-headers proposal exists specifically because every API picked its own names and formats for years, GitHub's Reset-as-timestamp, Twitter's similar approach, and plenty of others doing something slightly different again. AIOZ's Retry-After-as-seconds choice actually sits closer to the semantics of the standard HTTP Retry-After header, which RFC 9110 defines as either a date or a number of seconds, than to the vendor-specific Reset convention, a defensible design choice on its own, just not the one most developers will have already internalized from the bigger platforms.

What a 429 actually looks like

Exceeding a limit returns a 429 Too Many Requests status with a documented error message format: "Too many requests. Please wait X seconds before retrying." The same X-RateLimit-Retry-After header that's present on every successful response is what actually carries the precise wait time on a 429 as well, not a separate header that only shows up on the rejection. AIOZ's own guidance for handling this is direct: scale down request volume and return the failed, rate-limited requests to a retry queue based on that header's value, rather than treating a 429 as a hard failure to surface to an end user immediately.

A practical handling pattern

Two layers, working together rather than one replacing the other. Proactively, check X-RateLimit-Remaining on every response, and once it drops close to zero, deliberately slow down before a 429 ever happens, rather than continuing at full speed until the server forces a stop. Reactively, when a 429 does arrive anyway, read X-RateLimit-Retry-After and wait exactly that many seconds before the next attempt, no guessing, no computed backoff, the server has already done that math and published the answer. That second point is worth being explicit about because it contradicts a common default: many rate-limit handling guides recommend exponential backoff, doubling the wait time on each successive failure, specifically for the case where a server gives no precise guidance at all. AIOZ does give precise guidance, so exponential backoff isn't the better choice here, it's a worse one, needlessly waiting longer than the server actually requires, or retrying sooner than the stated window and risking another 429 if the backoff formula happens to undershoot it. Reserve exponential backoff for genuinely uncertain failures, a dropped connection or a 5xx server error with no rate-limit header attached at all, and use the server's own stated number whenever it's actually given, which AIOZ's X-RateLimit-Retry-After reliably is. In practice, the two layers reduce to something close to this:

const res = await fetch(url, options)

const remaining = Number(res.headers.get('X-RateLimit-Remaining'))
if (remaining <= 2) {
  await sleep(500) // proactive: slow down before a 429 happens
}

if (res.status === 429) {
  const waitSeconds = Number(res.headers.get('X-RateLimit-Retry-After'))
  await sleep(waitSeconds * 1000) // reactive: wait exactly what the server said
  return fetch(url, options)
}

Nothing exotic, a threshold check on the way in, an exact wait on the way out if the threshold check wasn't enough to avoid the 429 anyway. The proactive half matters more than it looks for anything running concurrent requests, a burst of parallel uploads can blow through X-RateLimit-Remaining between one response and the next request being sent, so checking on every response rather than only after a failure is what actually keeps a busy integration under the limit instead of just reacting to it after the fact.

Frequently Asked Questions

What are AIOZ Stream's exact rate limits?
100 requests per minute for uploads, 200 for writes, and 500 for reads, three separate limits rather than one shared budget.

What headers does AIOZ Stream return for rate limiting?
X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Retry-After on every response.

Why is X-RateLimit-Retry-After different from what I'd expect?
Most APIs use X-RateLimit-Reset with a Unix timestamp for this concept. AIOZ names it differently and returns seconds remaining instead of an absolute timestamp, worth checking for explicitly if reusing rate-limit handling code built against another API's convention.

What does a 429 response from AIOZ Stream actually contain?
A 429 Too Many Requests status, an error message reading "Too many requests. Please wait X seconds before retrying," and the same X-RateLimit-Retry-After header carrying the precise wait time.

Should I use exponential backoff when I hit a 429?
Not when the server tells you exactly how long to wait. Use the X-RateLimit-Retry-After value directly; reserve exponential backoff for failures with no precise guidance, like dropped connections or unrelated 5xx errors.

Do uploads, writes, and reads share the same rate limit?
No. Each has its own separate per-minute budget, 100/200/500 respectively, so a read-heavy workflow has far more headroom than an upload-heavy one.

Related Reading

• What Is DRM and Do You Need It: another production-readiness gap worth checking before launch, alongside rate limits
• Building a Video Analytics Dashboard: how a dashboard polling multiple analytics endpoints stays under the 500 req/min read limit
• AIOZ Stream Developer Guide: the full API surface these rate limits apply across
• Getting Started with the AIOZ Stream Node.js SDK: the client library documented to handle pagination and token refresh automatically, rate limits are a separate concern to handle explicitly
• Getting Started with the AIOZ Stream Go SDK Client: Go's explicit error-return pattern this article's 429 handling logic fits naturally into
• Chunked Video Upload Tutorial: 50-200MB Parts Explained: the upload-specific 100 req/min limit this article names directly applies to
• Event-Driven Video Pipelines with AIOZ Stream Webhooks: an event-driven alternative that avoids the read-limit pressure of polling for status instead

References

• AIOZ Stream API Limit documentation: the exact rate limits, header names, and 429 format quoted above
• GitHub: Rate limits for the REST API: the more common X-RateLimit-Reset convention referenced as a contrast above
• IETF: RateLimit header fields for HTTP: the standardization effort referenced above, showing why rate-limit header naming varies by API in the first place