API rate limits

For uninterrupted access to 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.

Bill.com API rate limit is calculated as the number of API requests per developer key per hour. In addition, the API concurrent rate limit is calculated as the number of simultaneous API requests per developer key per organization.

Bill.com API rate limits

The rate limit for Bill.com API requests per developer key per hour is 18000. In addition, the rate limit for /Login.json and /ListOrgs.json API requests per developer key per hour is 200.

When you reach this limit, you receive the BDC_1144 error. All subsequent API requests must wait until the beginning of the next hour.

{
  "response_status" : 1,
  "response_message" : "Error",
  "response_data" : {
    "error_code" : "BDC_1144",
    "error_message" : "Max number of allowed requests per hour reached: 18000."
  }
}

Bill.com API concurrent rate limits

The concurrent rate limit for Bill.com 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.

{
  "response_status" : 1,
  "response_message" : "Error",
  "response_data" : {
    "error_code" : "BDC_1322",
    "error_message" : "Max number of concurrent requests per organization reached."
  }
}

Implementing exponential backoff

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

In this Python example, when you hit the Bill.com 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).

📘

NOTE

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

import time, random, requests, json

max_retry = 12
retry = 0

while retry < max_retry:

    # Make a Bill.com API call (Read a vendor)
    url = 'https://api-sandbox.bill.com/v2/Crud/Read/Vendor.json'
    sid = '{session_id}'
    dev_key = '{developer_key}'
    payload = {
"sessionId": sid,
"devKey": dev_key,
"data" : '''{
    "id" : "{vendor_id}"
}'''
}

result = requests.post(url, data=payload)
parse_result = json.loads(result)

# If not rate limited, break & continue with your code logic
if parse_result['response_data']['error_code'] != "BDC_1144":
  break

# If rate limited, add exponential backoff
time.sleep(2 ** retry)
retry = retry + 1

Did this page help you?