Rate Limiting

The number of API calls is limited. Each API call returns two additional headers, which provide further rate limiting information:

X-Rate-Limit-Remaining – the number of requests left for the time window
X-Rate-Limit-Reset – time at UTC epoch seconds a new time window starts

Time windows

The restriction always refers to perdiods (time windows) of 15 minutes. The measurement periods are determined on the following areas:
XX:00 – XX:14
XX:15 – XX:29
XX:30 – XX:44
XX:45 – XX:59
If a new time interval is reached, there is a new contingent. Unused requests can not be accumulated and transferred.

Error when the quota limit is exceeded

If you exceeded the maximum number of calls within an interval, the HTTP error code 429 is returned. The error message tells you when you will be able to accessed the API again.

<?xml version="1.0" encoding="UTF-8"?>
<errors>
    <error>Maximum number of requests (300 per 15 minutes) reached. Try again in 246 seconds.</error>
</errors>

Without registered app

If no app is registers there is a limitation of 300 requests per account for 15 minutes.
Attention! If there are several services that access as unregistered app in an account, the sum of all request must be less or equal 300. It may be that another service has already consumed the contingent for the account.

With registered app

If an app is registered (open “Settings > Administration > Apps” in Billomat), the contingent rises to the number of requests assured by your plan per account. E.g. if a registered app is used by 100 people and your plan includes 1,000 requests per 15 minutes, a total of 100,000 hits per time interval is available.
Requests an account can not be transferred to other accounts.
Please remember to add the HTTP header X-AppId and X-AppSecret to your requests. Otherwise, we can not assign the API calls to your app!

Webhooks

Webhooks do not consume contingent and help to save calls. Instead of periodically request data, it is useful in many cases to use Webhooks instead.

Need more?

If you need more available requests per time interval, then please talk to us. We will find a solution.