---
updatedAt: 2026-03-24T17:29:04.000Z
agentTools:
  projectIndex: https://developer.bill.com/llms.txt
---

# API rate limits

For uninterrupted access to BILL v3 API services, follow the API rate limit rules and use exponential backoff to space out your API requests.

## What is an API rate limit?

An API rate limit is the number of API requests your solution or users can make within a given time period.

| Limit                     | Description                                                                |
| :------------------------ | :------------------------------------------------------------------------- |
| API rate limit            | The number of API requests per developer key per hour                      |
| API concurrent rate limit | The number of simultaneous API requests per developer key per organization |

## BILL API rate limits

The rate limit for BILL API requests per developer key per hour is `20000`. When you reach this limit, you receive the `BDC_1144` error. All subsequent API requests must wait until the beginning of the next hour.

```json BDC_1144 error
[
    {
        "timestamp": "2026-12-25T00:00:00.000+00:00",
        "code": "BDC_1144",
        "severity": "ERROR",
        "category": "DOWNSTREAM",
        "message": "Max number of allowed requests per hour reached: 20000."
    }
]
```

> ❗️ Rate limit special cases
>
> There are special cases for the BILL API rate limits. The API login (`POST /v3/login`)  rate limit is `200` per developer key per hour.
>
> Any endpoint that sends a text message to a user is limited to `5` messages per minute. For example, the Generate MFA challenge (`POST /v3/mfa/challenge`) endpoint results in sending a text message to the registered phone number.

## BILL API concurrent rate limits

The concurrent rate limit for BILL API requests per developer key per organization is `3`.

When you reach this limit, you receive the `BDC_1322` error. All subsequent API requests fail until one concurrent request is completed.

```json BDC_1340 error
[
    {
        "timestamp": "2026-12-25T00:00:00.000+00:00",
        "code": "BDC_1322",
        "severity": "ERROR",
        "category": "DOWNSTREAM",
        "message": "Max number of concurrent requests per organization reached."
    }
]
```

## BILL Spend & Expense API rate limits

The BILL Spend & Expense API rate limit is `60` calls per token per minute.

## Implement exponential backoff

Implement exponential backoff in your code and appropriately space out your API requests to avoid hitting the BILL rate limits and concurrent rate limits.

In this Python example, when you hit the BILL rate limits and receive the `BDC_1144` error, the `time.sleep()` function is used to set a backoff in seconds before retrying the API request.

The delay in seconds is calculated as `2 ^ (number of unsuccessful retries)`.

> 👍 `max_retry = 12`
>
> In the example, `max_retry` is set as `12` for the maximum possible backoff time in seconds to go past one hour. For BILL rate limits, this logic ensures that all subsequent API requests wait until the beginning of the next hour.

```python Exponential backoff Python example
import time, requests, json

# Set your session ID & developer key
session_id = "set_your_session_id"
developer_key = "set_your_developer_key"

headers = {
  "Accept": "application/json",
  "Content-Type": "application/json",
  "sessionId": session_id,
  "devKey": developer_key
}

max_retry = 12
retry = 0

while retry < max_retry:
  # Make a BILL API call (Get list of vendors)
  url = "https://gateway.stage.bill.com/connect/v3/vendors"

  result = requests.get(url, headers=headers)
    
  # If not rate limited, break & continue with your code logic
  if json.loads(result.text)[0]['code'] != "BDC_1144":
    break
  else:
    # If rate limited, add exponential backoff
    time.sleep(2 ** retry)
    retry = retry + 1
```