What is the meaning of X-Request-Count header in "429 TooManyRequests" error response?

[svetach1]

Hi,

I have an application that accesses repository data in BitBucket cloud via the API like so:
https://api.bitbucket.org/2.0/repositories/{username}/{repo}/refs/branches/master

In the last few days the application started receiving a lot of "429 TooManyRequests" errors, seemingly without increasing the amount of calls being made.
All the calls are authenticated with the same user.
As far as I understand from here the rate limit for such calls is a rolling window of 1000 requests per hour, right?

I have a few questions that might help me find what is causing the issue:
1. The error responses include the X-Request-Count header - what is the meaning of this header and its value?
Is it the total number of requests made in the rolling hour?
If so, then the header's value in a "429 TooManyRequests" response should always be over 1000, right?
The reason I'm asking is that in some responses the header value was much lower than that, e.g. 268, 308, 811 - how can this be explained?

2. Another strange observation regarding the X-Request-Count header is that sometimes 2 error responses received at the same time (on the second) contain vastly different values.
For example, 268 in one response and 1570 in another.
How is that possible?
Can this indicate an issue with the API rate limiting logic? Are there any known issues in this area?

3. Most of the API calls made by the application is to get the details of a branch in the repository (the url example above).
This request is made with the If-None-Match header set to the branch's latest etag value and when successful, the call returns "304 NotModified" status code.
Do such requests count against the API rate limit (1000)?
As far as I know, in Github they are not.

4. Another frequent API call made by the application is to obtain access tokens via the "https://bitbucket.org/site/oauth2/access_token" url.
Do those calls count against the same rate limit of 1000 requests per hour?

5. In general, were there any changes lately to the way API rate limits are calculated?

Any insights will be highly appreciated.

[Daniil Penkin]

Hello @svetach1 ,

Thanks for reaching out and welcome to the Community!

As far as I understand from here the rate limit for such calls is a rolling window of 1000 requests per hour, right?

Yes, this is correct. Authenticated calls are counter per user, unauthenticated calls are counted per IP.

The error responses include the X-Request-Count header - what is the meaning of this header and its value?

This header has nothing to do with rate limiting. It denotes the total number of requests served by the given backend worker. So it doesn't give much value for external API consumers and is more of an internal metadata.

Unfortunately, Bitbucket API currently doesn't provide any hint on the rate limit quota left/exceeded. Here's a feature request for this: BCLOUD-13931. Please vote for it so that we know you need this and so that you are notified when we make any updates to that ticket.

Another strange observation regarding the X-Request-Count header is that sometimes 2 error responses received at the same time (on the second) contain vastly different values.

This means your requests were served by two different workers of different "age" in terms of how many requests each of them served in the past.

This request is made with the If-None-Match header set to the branch's latest etag value and when successful, the call returns "304 NotModified" status code.
Do such requests count against the API rate limit (1000)?

I'm not sure about this one, sorry. Let me check that next week and get back to you here.

Another frequent API call made by the application is to obtain access tokens via the "https://bitbucket.org/site/oauth2/access_token" url.
Do those calls count against the same rate limit of 1000 requests per hour?

No, they don't count against the API quota.

In general, were there any changes lately to the way API rate limits are calculated?

None that I'm aware of.

Is you app a Bitbucket Connect App? If so, is it installed into multiple accounts?

Hope this helps.

Cheers,
Daniil

[svetach1]

Thank you very much for the answers, it certainly clarified a few things for me.

I really hope that the feature request you mentioned will be implemented, sure will vote for it.

To your question, the app is not a Bitbucket Connect App.

Looking forward to hearing from you regarding the conditional requests rate limit (the ones with the etag in the If-None-Match header), it will really help understand the issue I'm experiencing.

[svetach1]

Hi @Daniil Penkin ,

Are there any news regarding the If-None-Match requests?

Thanks.

[Daniil Penkin]

Hi @svetach1,

I'm sorry for the huge delay, had to confirm this in few places. From what I've found, such requests don't count into the API limit.

Cheers,
Daniil