Bitbucket Cloud Rate Limit Troubleshooting

Summary

Rate limiting appears in Bitbucket Cloud instances in two main ways:

"Something went wrong" in Bitbucket UI

When you navigate to different pages of your Bitbucket workspace and repos, you see the following error:

"Something went wrong...while we check things on our end, contact support if the problem persists."

You can use the developer tools in your browser to look for "429 (too many requests)" error codes in your browser's Console.

See instructions to open developer tools for Chrome, Firefox, Microsoft Edge, or Safari.

429 or rate limit error in Bitbucket API response

When you make an API call with Bitbucket Cloud's APIs, you get a 429 response code or the response:

"Rate limit for this resource has been exceeded."

Solution

Understand Bitbucket Cloud rate limits

The support team can't increase rate limits. The only way to do so is as described in our documentation: Scaled rate limits.

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. These limits are in place to provide stable performance for all users across the platform and prevent abuse from bad actors.

The documentation page API request limits explains how calls are measured and what the request limits are.

• Unauthenticated calls are measured against a specific IP address

• Authenticated calls are measured against the user ID

  • If you use the username and app password of a user, the calls are measured against this user

  • If you use an access token, the calls are measured against this token. Each access token has its own rate limit allowance

  • If you use OAuth, the calls are measured against the OAuth consumer, regardless of which user created the consumer

Please also check the Scaled rate limits section. Workspaces on the Standard or Premium plan with more than 100 paid users get an additional 10 API requests per hour per paid user beyond the initial 100. This only applies to:

• Workspace, project, repository access tokens for authentication or requests through programmatic access via a Forge app

Note: For Forge programmatic access, the scaled rate limits are available to API requests using the asApp app user.

Avoid Bitbucket rate limits with these mitigation steps

Below, see some suggested mitigation steps to avoid exceeding the rate limits. Please note that this list is not exhaustive and only covers commonly used mitigation steps.

Use (multiple) access tokens

Each token has its own rate limit allowance, meaning that requests made with token A will not be measured against token B.

• You can use repository, project, or workspace Access Tokens as an alternative to an App password (user-based access tokens) or OAuth

• Access Tokens are linked to a repository, project, or workspace based on where they’re created, and 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

• Access tokens can use Scaled rate limits if the requirements are met.

Delays between calls

• If you make frequent API calls to Bitbucket Cloud within one rolling hour, consider adding a delay/sleep of a few seconds 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

Divide calls between users

If you make all API calls to Bitbucket Cloud using one user account, and you don't want to use access tokens, consider setting up multiple users and making 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.

Use Pagination on API endpoints

When making API requests to endpoints that return a collection of objects, you can 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 with pagination using the following endpoint and query parameter:

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

Please note that the allowed maximum pagination value(25, 50, 100, etc) might be different for different API endpoints.

Forge app calls to Bitbucket

When you use a Forge app, 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.

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 the Jenkins Bitbucket Plugin to setup the webhook instead of Jenkins polling Bitbucket.

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

Avoid Concurrent Requests

To prevent reaching the rate limits, make API requests sequentially rather than concurrently. Implementing a queue system for requests can ensure that requests are processed in a serial manner.

Mutative Requests

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

Monitor the header X-RateLimit-NearLimit

Certain API endpoints return additional response headers. If an API call returns the header X-RateLimit-NearLimit, the value of this will be true once the remaining requests fall below 20%. For instance, for an API endpoint with a limit of 1,000 requests per hour, this header will indicate true when the remaining allowance drops below 200. You can monitor this header (where available) to see if you are close to the rate limit. The rate limit (total number of requests permitted per hour) for the endpoint you are calling will be indicated in the header X-RateLimit-Limit.

Request Backoff

If you receive a 429 response from Bitbucket (meaning that your rate limit has been reached), you will need to either use a different access token or authenticated user for the API calls or wait for a period of time. Once the request allowance can accrue for the current access token or user, requests can resume. Generally, the longer the back-off period, the more requests will be added back into the request budget.

If you can't figure out where the rate-limited requests are coming from, you can raise a support ticket, and ask the support team for more information.