# Meaning of x-ratelimit-remaining?

**URL:** <https://community.auth0.com/t/meaning-of-x-ratelimit-remaining/202312>\
**Category:** Get Help\
**Tags:** rate-limit, management-api\
**Created:** [August 6, 2026, 2:52pm UTC](https://community.auth0.com/t/meaning-of-x-ratelimit-remaining/202312 "2026-08-06T14:52:30Z")\
**Posts on this page:** 5\
**Page:** 1

<div class="post-metadata">

**Author:** ![anthony.tsang](https://sea1.discourse-cdn.com/auth0/user_avatar/community.auth0.com/anthony.tsang/32/79899_2.png) [@anthony.tsang](https://community.auth0.com/u/anthony.tsang)\
**Post date:** [August 6, 2026, 2:52pm UTC](https://community.auth0.com/t/meaning-of-x-ratelimit-remaining/202312/1 "2026-08-06T14:52:30Z")

</div>

When testing role migration script, I got HTTP 429, “Global limit has been reached”.

I understand APIs are rate limited, so I implemented a rate\_limit procedure, which is ran after every API call to wait when I am close to the limit.

The logic is like

```auto
(After an API call)
If HTTP header x-ratelimit-remaining < 3 then
   Sleep until x-ratelimit-reset

```

I understand that theoretically we can have API calls from other applications, so this is not 100% reliable. Please ignore this possibility for this post.

This did not work. I got HTTP 429 after a call returned `x-ratelimit-remaining=993`. I am sure nothing else made 993 calls between my 2 calls.

Is this because management API has a tight rate limit, and `x-ratelimit-remaining` is based on the maximum possible limit? If yes, why return this header? The value useless most of the time.

And then the only solution of HTTP 429 is to retry after `x-ratelimit-reset` FOR EVERY API call?

---

<div class="post-metadata">

**Author:** ![remus.ivan](https://sea1.discourse-cdn.com/auth0/user_avatar/community.auth0.com/remus.ivan/32/68771_2.png) [@remus.ivan](https://community.auth0.com/u/remus.ivan)\
**Post date:** [August 6, 2026, 7:19pm UTC](https://community.auth0.com/t/meaning-of-x-ratelimit-remaining/202312/3 "2026-08-06T19:19:30Z")

</div>

Hello @anthony.tsang.

Welcome to the Auth0 Community!

I understand that you are receiving **HTTP 429 “Global limit has been reached”** errors due to rate-limiting boundaries of the Management API, so lets clarify what is happening here.

To answer your question directly: this happens because Auth0 enforces _ **multiple layers of rate limits** _ simultaneously using a token bucket algorithm. Specifically, your role migration script hit a **burst limit** while it was running, even though your overall **sustained rate limit** had plenty of capacity left.

Here is a breakdown of why this occurs and how you can adjust your script.

**Burst Limits vs. Sustained Limits**  
Auth0 rate limits are divided into two concepts: the burst limit (the maximum number of rapid requests you can make in a fraction of a second) and the sustained limit (your total allowance over a longer window, like a minute). Because scripts like a role migration tool fire off multiple requests very rapidly, your script essentially emptied the instantaneous burst bucket before it had a chance to refill. Even though your minute-level allowance was fine, the sudden spike triggered the 429 error.

> [@anthony.tsang](#):
>
> why return this header?

The header isn’t useless, but it only tells half the story when running high-speed scripts. The headers returned on successful HTTP 200 responses are only tracking your larger, sustained per-minute bucket, which is why it accurately reported 993 remaining. Because the smaller burst limits refill on a sub-second basis, standard HTTP headers cannot update fast enough on successful calls to warn you that the burst bucket is draining.

> [@anthony.tsang](#):
>
> retry after `x-ratelimit-reset` FOR EVERY API call?

Absolutely not. If you wait for the minute-level reset timestamp on every call, your migration script will take much longer than necessary. Because the burst bucket refills continuously (usually within a second), your wait time after a 429 is actually very short.

To fix this in your script, you can replace your current logic with these two adjustments:

- **Add a small, fixed delay:** Introduce a slight delay directly in your script’s loop, such as a 100ms or 200ms sleep between each API call. This naturally throttles your script just enough to stay under the burst limit threshold, preventing the 429 errors from happening in the first place.

- **Rely on the** `Retry-After` **header** , that you can check more about in our [Back-Channel Login flow - Status Check](https://auth0.com/docs/api/authentication/login/check-back-channel-login-status) documentation. If your script does hit a 429, do not look at the `x-ratelimit-reset` timestamp. Instead, configure your error handling to read the `Retry-After` HTTP header included in the 429 response itself. This header will tell you the exact number of seconds (often just 1 or 2) you need to pause before the burst bucket has recovered.

You can read more about how the token bucket algorithm handles these burst versus sustained scenarios in the [Rate Limit Use Cases](https://auth0.com/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-use-cases#appi-public-performance-burst-only) documentation.

I hope this helps and if you have further questions please let me know!  
Best regards,  
Remus

---

<div class="post-metadata">

**Author:** ![anthony.tsang](https://sea1.discourse-cdn.com/auth0/user_avatar/community.auth0.com/anthony.tsang/32/79899_2.png) [@anthony.tsang](https://community.auth0.com/u/anthony.tsang)\
**Post date:** [August 7, 2026, 9:10am UTC](https://community.auth0.com/t/meaning-of-x-ratelimit-remaining/202312/4 "2026-08-07T09:10:49Z")

</div>

Is the “Retry-After” header included only for requests hitting HTTP 429 (or 503)? For successful calls and I don’t receive this header.

---

<div class="post-metadata">

**Author:** ![remus.ivan](https://sea1.discourse-cdn.com/auth0/user_avatar/community.auth0.com/remus.ivan/32/68771_2.png) [@remus.ivan](https://community.auth0.com/u/remus.ivan)\
**Post date:** [August 7, 2026, 3:31pm UTC](https://community.auth0.com/t/meaning-of-x-ratelimit-remaining/202312/5 "2026-08-07T15:31:00Z")

</div>

Hi @anthony.tsang,

The HTTP **`Retry-After`** [response header](https://developer.mozilla.org/en-US/docs/Glossary/Response_header) indicates how long the user agent should wait before making a follow-up request. This header is used:

- In a [`503 Service Unavailable`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/503) response, this indicates how long the service is expected to be unavailable.
- In a [`429 Too Many Requests`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/429) response, this indicates how long to wait before making a new request.

This is also detailed on this page - [Retry-After header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Retry-After).

The purpose of `Retry-After` is specifically to act as an emergency “cool down” directive when a request has been rejected. Including it on a successful (HTTP 200) response wouldn’t make sense because the server handled your request successfully and there is nothing to retry.

Your migration script could follow a dual-approach path:

1. **The HTTP 200 path:**  
Keep your script running smoothly by adding a tiny, proactive delay between calls (e.g., sleeping 100ms–200ms after each call). This acts as a preventative speed limit so you don’t hit the burst threshold in the first place.

2. **The "Error - HTTP 429 path:**  
If a call fails with a 429, write your error-handling block (usually a `try and catch` one) to check the response headers specifically for `Retry-After`. Pause your script for the number of seconds specified in that header, and then try the failed request again.

Hope this helps!  
Best regards,  
Remus

---

<div class="post-metadata">

**Author:** ![system](https://global.discourse-cdn.com/auth0/original/3X/b/5/b560f266932fcce5d57f09a6595bd50518cae3f3.jpeg) [@system](https://community.auth0.com/u/system)\
**Post date:** [August 9, 2026, 3:31pm UTC](https://community.auth0.com/t/meaning-of-x-ratelimit-remaining/202312/6 "2026-08-09T15:31:30Z")

</div>

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.
