> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/continuous-delivery/troubleshooting-and-resources/knowledge-base-article/bitbucket-api-limit.md).

# Preventing Bitbucket API Rate Limits with Webhook Caching

Configure webhook caching in Harness to prevent Bitbucket API rate limit errors.

This knowledge base article explains how setting up a webhook sync can help prevent reaching the Bitbucket API rate limit.

***

## What you will learn from this topic

* **API rate limits:** What causes Bitbucket API rate limits and the error messages they produce.
* **Webhook caching:** How a webhook connection caches files at Harness to reduce API calls.
* **Webhook setup:** How to configure a webhook at account, organization, or project level to enable caching.

***

## Before you begin

* **Bitbucket connector:** You need an existing Bitbucket connector in Harness. Go to [Bitbucket connector settings](https://developer.harness.io/docs/platform/connectors/code-repositories/bitbucket-connector-settings-reference) to create one.

***

## API rate limits

Bitbucket rate limits are [the number of API requests that you can make within a specific amount of time (1 hour according to current documentation)](https://support.atlassian.com/bitbucket-cloud/docs/api-request-limits/). When the number of API requests in a specific period is high, it can prevent remote entities from working. The rate limits are divided into 1-hour rolling windows for the calls.

### Error messages

The following error messages can occur when Bitbucket rate limits are reached:

```
Response message: Please try these out: 
1. Please try and rotate your tokens used for GIT operations.
2. Please check your rate limits with your BitBucket GIT provider
                  Rate limit reached on BitBucket provider.
                  Failed to perform GIT operation.
```

```
errorMessage: "Failed to fetch file [path/to/templateorpipeline.yaml] from Bitbucket due to error : No commit found."
```

Go to [Bitbucket API request limits](https://support.atlassian.com/bitbucket-cloud/docs/api-request-limits/) to review the different types of limits.

***

## Ease Bitbucket API limits with a webhook connection

Without a webhook connection, changes made on either the Git repository or Harness are automatically synchronized, but each piece of the pipeline stored remotely in Bitbucket requires an API call. For example, input sets, templates, and each connector may be stored in Bitbucket and need to be reconciled and refreshed. This can add up to a large number of Bitbucket API calls, even for authenticated accounts.

When a webhook connection is established, files are cached at Harness, creating a copy of the Harness files in the repository. Instead of making frequent requests to the Bitbucket API for every operation, the system can rely on the cached data for all tasks, reducing the risk of reaching API limits.

***

## Set up a webhook for caching

To set up caching with your Bitbucket repository, use the following navigation paths based on your scope:

**Account level:** Account Settings → Account-level Resources → Webhooks → New Webhook ![](https://3694223630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fy1JhZ4oKIppwY7d5AhPj%2Fuploads%2Fgit-blob-085205a5d68ddc71ae2952048a403e402a74d634%2Fbitbucket-newwebhook.png?alt=media)

**Organization level:** Organization Resources → Organization-level Resources → Webhooks → New Webhook

**Project level:** Project Settings → Project-level Resources → Webhooks → New Webhook

### Webhook configuration steps

![](https://3694223630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fy1JhZ4oKIppwY7d5AhPj%2Fuploads%2Fgit-blob-dda678216e52f0d11fda08a5205733bce87b5464%2Fbitbucket-webhooksettings.png?alt=media)

Follow these steps to configure the webhook:

1. Provide the appropriate name for the connector and select `Git` as the webhook type.
2. In the Git connector, select the Bitbucket connector that you have already created. Go to [Bitbucket connector settings](https://developer.harness.io/docs/platform/connectors/code-repositories/bitbucket-connector-settings-reference) to create a connector.
3. In **Repository**, select the Bitbucket repository where your Harness entities are stored. If you are storing your entities in more than one repository, you must create a separate webhook for each repository.
4. In **Folder Path**, specify the directory (for example, `.harness/`). This is optional. If no folder is specified, all folders are used.

{% hint style="info" %}
Harness tracks the .harness folder by default in all webhooks.
{% endhint %}

5. Click **Add** to register the webhook.
6. Once synced, events appear in the **Events** tab under Webhooks, including event IDs for troubleshooting.
7. Entities that are being synchronized display a green dot showing the last synchronization time. ![](https://3694223630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fy1JhZ4oKIppwY7d5AhPj%2Fuploads%2Fgit-blob-7a07235f566a8575d873647422ea696a83ffb69f%2Fbitbucket-sync.png?alt=media)

{% hint style="info" %}
**Caching notes**

* The file cache duration is set to 30 days.
* Create a webhook at the account level so all pipelines pulling from the repository benefit from the cache.
* You may still encounter issues depending on the number of changes pushed in each commit.
* Each repository requires a separate webhook. For example, setting a webhook for `abc123corp` does not cache data from `harness123`.
  {% endhint %}

***

## Next steps

After configuring webhook caching, Harness files are synchronized from Bitbucket and API calls are reduced.

* [Bitbucket connector settings](https://developer.harness.io/docs/platform/connectors/code-repositories/bitbucket-connector-settings-reference): Review connector configuration options for Bitbucket.
* [Triggers and webhooks](https://developer.harness.io/docs/platform/triggers/): Automate pipeline runs based on webhook events.

{% @harness-feedback/feedback %}