Summary

This article will guide customers in identifying when their Bitbucket Cloud API requests are being rate limited, how to mitigate it using known or proven methods, and when to contact the Bitbucket Cloud support team.

Bitbucket Rate Limit

The current Bitbucket Cloud API request rate limit is outlined in API request limits. We know these rate limits may not be sufficient for your use case, and the feature request Increase API Rate Limits was created to increase these limits.

Why Rate Limit

Bitbucket Cloud has rate limits that control the number of API requests that users can send to Bitbucket Cloud within any rolling one-hour window. It is in place to provide stable performance for all users across the platform and prevent abuse from bad actors.

Please note that API request rate limiting is applied per API endpoint and is currently not adjustable based on the workspace plan or the customer tier.

Scenarios and troubleshooting approach

Use the following troubleshooting steps to identify if your API requests are rate limited.

Scenario A: Bitbucket UI (bitbucket.org)

Steps to identify if your user is being rate limited while navigating the bitbucket.org interface while logged in.

Observed behavior

• An authenticated user receives an error in the Bitbucket UI "Something went wrong".

• When opening the DevTools console and refreshing the page, the user observes," 429 (Too many requests)".

Use the following steps based on your browser to access the developer tool console.

We know the messaging can be improved and have a feature request Improve API error message to address this.

Scenario B: API/Integration

How do you identify if you’ve been rate-limited on the Bitbucket API?

If you observe one of the following error messages in the log, then you are being rate limited

• 429

• Rate limit for this resource has been exceeded

Recommended mitigation steps

Please note that this list is not exhaustive and only covers commonly used mitigation steps.

OAuth Calls and User Limitations

All API requests made through OAuth are treated as originating from a single user, regardless of which user created the OAuth consumer within the workspace. This means that the rate limit calculations consider these requests collectively from one account, potentially impacting your rate limit usage faster than anticipated. To mitigate it, use repository, project, or workspace Access Tokens as an alternative to an App password (user-based access tokens)

Delays between calls

If you make frequent API calls to Bitbucket Cloud within one rolling hour.

• Adding a delay/sleep of 5-10 minutes to API calls to avoid reaching the rate limit (Please note that the rate limit hour is a rolling hour, not a "fixed clock hour")

• If you use a third-party integration like Jenkins that polls Bitbucket regularly, reduce the number of polls.

Dividing the calls between users

If you make all API calls to Bitbucket Cloud using one user account.

• Set up multiple users and make API calls from multiple authenticated users to avoid hitting the rate limit. This will allow you to divide API calls between two or more authenticated users to stay within API limits on the rolling 1-hour window. 

Best practices

Webhooks

Take advantage of webhooks instead of Bitbucket Cloud APIs to poll for events. Webhooks provide a way to configure Bitbucket Cloud to send requests to your server (or another external service) whenever certain events occur in Bitbucket Cloud instead of you making the API calls to Bitbucket Cloud. For example, if you are using Jenkins as a CI/CD tool, use Jenkins Bitbucket Plugin to set up the Webhook instead of Jenkins polling Bitbucket.

Webhooks have no restrictions, unlike Bitbucket Cloud API requests, which are rate limited.

Use Access Tokens

• Use repository, project, or workspace Access Tokens as an alternative to an App password (user-based access tokens).

• Access Tokens are linked to a repository, project, or workspace based on where they’re created. They can be used for scripting tasks and integrating tools (such as CI/CD tools) with Bitbucket Cloud.

• Access Tokens are intended to be used by a single application with limited permissions.

Each token has its own rate limit allowance, meaning generating tokens for particular resources, such as a repository or project, is possible. This allows for better management of rate limiting issues, primarily if existing tokens are used across multiple resources.

Use Forge

Use Forge apps for programmatic access to Bitbucket APIs. Authenticated calls to Bitbucket APIs can be made as the app (asApp) or as the user using the app (asUser). We recommend making requests as the app so you can also take advantage of scaled rate limits for the workspace the app is installed in.

Avoid Concurrent Requests

To prevent reaching your rate limit, make API requests sequentially rather than concurrently. By implementing a queue system for requests, you can ensure that requests are processed in a serially.

Mutative Requests

Making numerous mutative requests, such as POST, PUT, and DELETE, in rapid succession is discouraged. It is advisable to introduce a minimum one-second interval between these requests for better performance and stability.

Pagination

When making API requests to endpoints that return a collection of objects, customers should use pagination to reduce the number of requests made to Bitbucket. Use the pagelen query parameter to increase the number of results returned.

For example a list of repositories in a workspace can be retrieved using pagination as follows:

https://api.bitbucket.org/2.0/repositories/{workspace}?pagelen=100

Request Backoff

In the event that you receive a 429 response from Bitbucket (meaning that your rate limit has been reached), we recommend backing off for a period of time so your request allowance can once again accrue. Generally, the longer the back off period, the more requests will be added back into the request budget.

Customers should use the X-RateLimit-NearLimit response header as an indication to reduce API requests and begin the process of backing off. This header contains a boolean value that switches to ‘true’ once the remaining requests fall below 20%. For instance, with a limit of 1,000 requests per hour, this header will indicate ‘true’ when the remaining allowance drops below 200.