Link

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 second. 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.

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

Soft Limit Hard Limit
One request/second on average (measured over a period of 10 minutes) with a burst of up to 10 requests/second for a maximum of 20 seconds. The hard limit will depend on the current load of the system. It’s usually 2-3 times the soft limit. The max allowance would be an average of 3 requests/second with a burst of up to 30 requests/second for no more than 20 seconds.

Note: We might adjust the rate limit in the future.

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

API Endpoint
Offers
GET /booking/v1/offers
GET /booking/v1/rate-plan-offers
GET /booking/v1/service-offers
GET /booking/v1/offer-index
Reservations
PATCH /booking/v1/reservations/{id}
DELETE ​/booking​/v1​/reservations​/{id}​/services
ReservationActions
PUT ​/booking​/v1​/reservation-actions​/{id}​/assign-unit
PUT ​/booking​/v1​/reservation-actions​/{id}​/assign-unit​/{unitId}
PUT ​/booking​/v1​/reservation-actions​/{id}​/unassign-units
PUT ​/booking​/v1​/reservation-actions​/{id}​/checkin
PUT ​/booking​/v1​/reservation-actions​/{id}​/checkout
PUT ​/booking​/v1​/reservation-actions​/{id}​/cancel
PUT ​/booking​/v1​/reservation-actions​/{id}​/noshow
PUT ​/booking​/v1​/reservation-actions​/{id}​/amend
PUT ​/booking​/v1​/reservation-actions​/{id}​/amend​/$force
PUT ​/booking​/v1​/reservation-actions​/{id}​/book-service
FolioActions
POST ​/finance​/v1​/folio-actions​/{folioId}​/charges
POST ​/finance​/v1​/folio-actions​/{folioId}​/transitory-charges
POST ​/finance​/v1​/folio-actions​/{folioId}​/cancellation-fee
POST ​/finance​/v1​/folio-actions​/{folioId}​/no-show-fee
PUT ​/finance​/v1​/folio-actions​/{folioId}​/move-charges
PUT ​/finance​/v1​/folio-actions​/bulk-move
PUT ​/finance​/v1​/folio-actions​/{folioId}​/move-all-charges
POST ​/finance​/v1​/folio-actions​/{folioId}​/charges​/{chargeId}​/allowances
POST ​/finance​/v1​/folio-actions​/{folioId}​/allowances
PUT ​/finance​/v1​/folio-actions​/{folioId}​/post-charges
PUT ​/finance​/v1​/folio-actions​/{folioId}​/move-payments
POST ​/finance​/v1​/folio-actions​/{folioId}​/correct
POST ​/finance​/v1​/folio-actions​/{folioId}​/charges​/{chargeId}​/split
POST ​/finance​/v1​/folio-actions​/{folioId}​/payments​/{paymentId}​/split
FolioPayments
POST ​/finance​/v1​/folios​/{folioId}​/payments
POST ​/finance​/v1​/folios​/{folioId}​/payments​/by-terminal
POST ​/finance​/v1​/folios​/{folioId}​/payments​/by-authorization
POST ​/finance​/v1​/folios​/{folioId}​/payments​/by-payment-account
POST ​/finance​/v1​/folios​/{folioId}​/payments​/by-link
POST ​/finance​/v1​/folios​/{folioId}​/refunds
POST ​/finance​/v1​/folios​/{folioId}​/payments​/{paymentId}​/refunds
/inventory/v1/ - All Inventory API endpoints (until 1-Oct-2020).
/rateplan/v1/ - All Rate Plan API endpoints (until 1-Oct-2020).
GET endpoints

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

Note: 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.

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 https://github.com/apaleo/api, 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 https://github.com/apaleo/api 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.