X-RateLimit Headers and HTTP 429: API Rate Limits Explained

X-RateLimit headers tell your client how many API requests it can still send and when it can send more. AIOZ Stream returns three on every response: X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Retry-After. Go past 100 uploads, 200 writes or 500 reads per minute and you get HTTP 429.

TL;DR:

• AIOZ Stream's documented limits are 100 requests per minute for uploads, 200 for writes and 500 for reads. These are three separate budgets, not one shared limit.
• Every response carries three headers: X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Retry-After. The last one differs from the common X-RateLimit-Reset name other APIs use.
• X-RateLimit-Retry-After gives the seconds left until the window resets, not a Unix timestamp. That matters if your code expects the common convention.
• A 429 response carries the message "Too many requests. Please wait X seconds before retrying." plus the same Retry-After value your client should already be tracking.
• When the API tells you how long to wait, use that number. Exponential backoff is for servers that don't give you one, and AIOZ does.

Most rate-limit code you already have will work against AIOZ Stream's API. One header is the exception. It is named and shaped differently from the GitHub and Zendesk convention. Miss that, and the bug only shows up once real traffic hits a limit in production.

What are AIOZ Stream's rate limits?

AIOZ Stream gives you three separate budgets, not one shared pool. Uploads are capped at 100 requests per minute, writes at 200 and reads at 500. That split changes how you should plan your request budget. A bulk job that lists or checks videos draws on the read budget, so it has five times the headroom of an upload-heavy workflow. If you treat every call as drawing from one combined limit, you will underestimate what read operations can do.

What do the X-RateLimit headers mean?

Every API response carries three headers, according to AIOZ's rate limit documentation. X-RateLimit-Limit shows "the applied request limit per minute." X-RateLimit-Remaining shows "the number of available requests you have left for the current time window." Both behave the way you would expect if you have used a rate-limited API before.

The third header is where AIOZ's naming diverges. It is X-RateLimit-Retry-After, not the X-RateLimit-Reset name that GitHub, Zendesk and several other major APIs use. The value differs too. AIOZ describes it as "the number of seconds left until the current rate limit window resets," so it is a countdown. The common X-RateLimit-Reset convention usually returns a Unix epoch timestamp instead.

That difference breaks code in two ways. Code that looks for a header called X-RateLimit-Reset will silently find nothing. Code that finds X-RateLimit-Retry-After but parses it as a timestamp will compute a nonsensical wait time.

AIOZ isn't being unusual here. Rate-limit headers have never been formally standardized, which is why the IETF's draft-polli-ratelimit-headers proposal exists. For years every API picked its own names and formats. AIOZ's seconds-based value sits closer to the standard HTTP Retry-After header, which RFC 9110 defines as either a date or a number of seconds. It's a defensible choice, just not the one most developers learned from the bigger platforms.

What does a 429 response look like?

Exceeding a limit returns a 429 Too Many Requests status with a documented message: "Too many requests. Please wait X seconds before retrying." The wait time travels in the same X-RateLimit-Retry-After header that every successful response carries. There is no separate header that only appears on the rejection. AIOZ's guidance is direct: scale down your request volume and put the rate-limited requests back in your queue, timed by that header. Don't surface a 429 to your end user as a hard failure.

A practical handling pattern

Use two layers that work together. The proactive layer checks X-RateLimit-Remaining on every response. When it drops close to zero, slow down before a 429 happens instead of running at full speed until the server stops you. The reactive layer handles the 429 that arrives anyway. Read X-RateLimit-Retry-After and wait exactly that many seconds before the next attempt. There's no guessing and no computed backoff, because the server has already done that math.

That second point contradicts a common default. Many rate-limit guides recommend exponential backoff, doubling the wait after each failure. That advice exists for servers that give no precise guidance. AIOZ does give it, so exponential backoff is the worse choice here. It either waits longer than the server requires, or it retries before the stated window ends and risks another 429. Keep exponential backoff for uncertain failures, such as a dropped connection or a 5xx error with no rate-limit header. 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, and an exact wait on the way out if the check wasn't enough. The proactive half matters most when you run concurrent requests. A burst of parallel uploads can drain X-RateLimit-Remaining between one response and the next request. Checking every response, not only failures, is what keeps a busy integration under the limit instead of reacting 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, not an absolute timestamp. Check for this if you reuse rate-limit code built for another API.

What does a 429 response from AIOZ Stream contain?
A 429 Too Many Requests status, the message "Too many requests. Please wait X seconds before retrying," and the same X-RateLimit-Retry-After header carrying the 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
• AIOZ Storage Rate Limit: Working Within 100 Requests/s: the request limit on AIOZ Storage
• AIOZ Pin Rate Limits: API, Public, and Premium Gateways: API and gateway limits on AIOZ Pin

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