Differentiation of 429 errors

There are 2 reasons a request can receive a 429 response. One for a per-second rate limit, and one for a per-day total limit.

But, the only way to potentially know which one you hit is to parse the message in the json. Could we possibly get an additional field added to the json error response maybe indicating which was hit?

"limit": "daily",   //other value could be "rate" for the per-second one 
 "message":"You have reached the maximum per-second rate limit for this API. Try again later."

In summary, it would be nice to “subclass” the 429 error if possible with a “which limit” was hit.

Next request- mostly related. There is a ‘X-RateLimit-Remaining’ That only seems to be returned on 200 responses. It doesn’t give us enough info to make proper rate limiting decisions. It would be nice if ALL responses contained something like these 3 examples:

429 response(per second exceeded)

"x-Ratelimit-category: heavy"
"X-RateLimit-daily-Remaining: 2000"
"x-ratelimit-daily-limit: 5000"
"x-ratelimit-rate-reset: 20"  // Means the 429 you just got exceeded the rate limit and you should wait 20s


429 response(daily exceeded)

"x-Ratelimit-category: heavy"
"X-RateLimit-daily-Remaining: 0"
"x-ratelimit-daily-limit: 5000"
"x-Retry-After: date-time-limit-resets "


200 response

"x-Ratelimit-category: resource-intensive"
"X-RateLimit-daily-Remaining: 500"
"x-ratelimit-daily-limit: 1000"

Hey @robert.macaulay,

Thank you for the suggestions, I will add this as a feature request. (ZOOM-156553)


1 Like

I see via the Changelog that the response headers X-RateLimit-Category and X-RateLimit-Type have been added to 429 responses, but the documentation has not yet been updated accordingly. Could you specify what the possible values for these headers are?

Hey @gwhitney,

We will get the docs updated. CC @shrijana.g.