# Rate Limiting

To ensure stability, performance, and fair usage, the Bermuda Commercial Bank RESTful Open Banking API enforces **rate limiting**. This prevents abuse and guarantees a consistent experience for all users.

## 🚦 What is Rate Limiting?

Rate limiting restricts the number of API requests a user or IP address can make within a specific time frame. Once the limit is reached, further requests are temporarily blocked.

## 🧭 Strategy: Fixed Window

The API uses a **fixed window rate limiting** approach. This means requests are counted within a defined time window, and once the limit is hit, no further requests are allowed until the window resets.

### 🔧 Current Configuration

- **Time Window:** 60 minutes
- **Request Limit:** 300 requests per user or IP address


📌 Example: If a user sends 300 requests within an hour, any additional requests during that hour will be blocked until the next 60-minute window begins.

### Virtual Accounts Specific Rate Limiting

- **Scope:** Endpoints whose path contains `virtual-accounts` (e.g., `POST …/virtual-accounts` for account creation).
- **Pacing rule:** **Global limit of 1 request every 2 seconds** for **virtual account creation** across all clients.
- **Handling:** Exceeding the pacing returns **429 Too Many Requests** (may include `Retry-After`). Space requests ≥2s and back off on 429.
- **Note:** This VA-specific pacing is **in addition to** the global fixed-window limit above.


## ⚠️ When the Limit is Exceeded

If the rate limit is exceeded, the API returns a **429 Too Many Requests** response, including a timestamp indicating when you can retry.

### 📉 Example Response


```json
{
  "error": "Rate limit exceeded",
  "message": "You have exceeded the 300 requests per 60 minutes limit. Please wait for the rate limit to reset.",
  "retry_after": "2023-12-31T23:59:59Z"
}
```

## ✅ Best Practices for Developers

1. **Track Usage**
Monitor your request count and avoid exceeding the limit.
2. **Graceful Handling**
Implement logic to catch `429` responses and back off appropriately.
3. **Use `retry_after`**
Honor the `retry_after` timestamp before retrying requests.
4. **Optimize API Calls**
Cache responses where possible and avoid redundant requests.
5. **Distribute Requests**
Spread requests over time rather than sending them in bursts.


## 🔧 Do You Need to Configure Anything?

No manual configuration is needed—rate limiting is handled by the API infrastructure. However, understanding these limits is essential for building efficient, user-friendly applications.

## 💬 Need Help?

If you have questions or require additional support, please consult the full API documentation or contact our support team at 📧 [api@bcb.bm](mailto:api@bcb.bm).