Rate Limiting

apaleo limits API call usage to maintain a high level of availability and ensure that we provide an excellent API experience to all our customers.

Rate limiting and throttling policies are designed to limit API access, but have different purposes: Rate limiter limits the number of requests received by the API within any given period. Throttling (concurrency limiter) shapes API access by smoothing spikes in traffic by limiting the number of active requests at any given time. apaleo calculates the throttling limit per Client ID and Account Code.

APIs reject requests that exceed the limit. It is necessary to guarantee the system’s stability and quick response times to every app and user.

Limits are set at two different levels:

Globally: Unless specified by an exemption every request to our APIs that returns an HTTP status code distinct to 429 counts towards a global limit per Client ID and Account Code.

By resource: Specified below in this page there is a list of API endpoints with different limits for a given resource per Client ID and Account Code.

An example: assuming a limit of 20 requests every 5 minutes and the endpoint PATCH /booking/v*/bookings/{id} the following requests will affect different RESOURCE limits, even though they are performed against the same API endpoint

• PATCH /booking/v1/bookings/BOOK-1
• PATCH /booking/v1/bookings/BOOK-2

so in a window of 5 minutes you can: PATCH BOOK-1 20 times and PATCH BOOK-2 20 times.

Reaching the limit for PATCH BOOK-1 doesn’t affect the limit for PATCH BOOK-2 and vice versa.

Also notice, the following calls will affect the same RESOURCE limit, even though they use the different API endpoints

• PATCH /booking/v1/bookings/BOOK-1
• PATCH /booking/v0-nsfw/bookings/BOOK-1

For consistent access to the API services, ensure that your apps adhere to the following rate limits and best practices.

We might adjust the rate limits in the future.

Live accounts

These are the rules that apply for access to apaleo Live accounts.

Throttling won’t apply to business-critical API calls for live accounts, like:

GET endpoints

The standard API rate limits apply to all the GET (read) endpoints unless specified in the list above.

Specific Resource limits

To be prepared for future changes, your app should be prepared to handle rate limiting on all endpoints, rather than just those that are listed above.

Development and Trial accounts

For requests made to Development and Trial accounts all endpoints are throttled with no exceptions. Below you can see the rules that apply:

• A total of 5 requests/second
• A total of 200 requests/minute

Specific Resource limits

What happens if my app hits the limit wall?

When you reach the limit, you receive the HTTP status code 429 Too many requests. Additionally, the server provides you with more information about which throttling limit you hit and when you can resume your calls. The response includes a Retry-After value, which specifies the number of seconds your application should wait before sending the next request.

StatusCode: 429
Content-Type: text/plain
Retry-After: 1
Apaleo-Tracking-Id: 0HM0MP4JURCKR:00000002

If you send a request before the retry value has elapsed, your request isn’t processed, and a new retry value is returned. If you don’t want to analyze those headers, you can try again in a few seconds. Throttled calls, of course, do not count towards your limit.

How to play nice with apaleo’s API?

We noticed that many API calls could be avoided when designing and leveraging a better API together:

• Use webhooks to get updated data - we have a webhook API where you can subscribe for changes instead of polling for changes. If you are missing events, request them at api@apaleo.com, and we’ll do our best to add them. For more information about webhooks, see the webhook guide.
• Avoid fetching single items in a list - some apps fetch a list and afterward every item in that list separately. After talking to the partners, we realized that it is usually just one or two fields missing in that list. Let us know at api@apaleo.com which fields are missing. We’ll do our best to add them to the list, so you save yourself and us the headache to fetch every item one by one.
• Avoid fetching data that’s not required - talking to some partners, we have noticed that sometimes data is fetched way too often, and not used during processing. Try to fetch data on demand. apaleo’s API can answer over 90% of the requests in < 500 milliseconds and over 50% in < 150 milliseconds.
• Cache frequently used data - Use caching for data that your app uses often.
• Breathe in, breathe out - Your app should stop making additional API requests until enough time has passed to retry. The recommended backoff time is one second.

Frequently asked questions

• Do you folks have an endpoint that returns all endpoints to which rate limiting is applicable?

  Sorry, we don’t have a rate-limit endpoint.

• What happens when my app hits the rate limit?

  Tell it to relax and try again after one second. The recommended backoff time is one second.

Working smarter instead of harder doesn’t just reduce our server bill, but it also reduces everyone’s carbon footprint.

If you have further questions regarding throttling and how to avoid hitting limits, reach out to our squad.