Rate Limiting to be Implemented in EscapiaNet API

In January, we had an incident in production caused by large UnitStay requests that impacted system performance of both EscapiaNet and Escapia. To prevent incidents like this in the future, we are implementing rate limiting for the EscapiaNet API. This will help ensure the integrity of our systems and improve availability and stability for you and the rest of our partners. We expect these changes to improve the performance of this API and protect the systems and our partners against unreliability that comes with excessive and erratic API calls.


Effective 3/23/20

  • Reducing the MaxUnitStayCountPerBatch value from 100 to 50 for the UnitStay action 

Effective 4/22/20

  • Monitoring period (requests will not be throttled)

Effective 4/29/20

  • Limit the # of units/minute for UnitStay (staydate) SOAP action enforced (“TooManyRequests” error response returned, requests throttled for the remainder of the time window)

  • Limit the # of calls/second on all other SOAP actions in the EscapiaNet API enforced (“TooManyRequests” error response returned, requests throttled for remainder of the window)

  • Rate limiting headers returned (see below)

Since we need to reserve the right to change the limits that trigger throttling based on our system needs, we will not publish the exact rates. The rate limits will primarily act as an upper bound that protects against API ‘attacks’, and do not anticipate these rates significantly affecting your applications. The majority of API users will not be affected by these limits, as long as they are calling the API at a consistent and reasonable rate. We will be continually evaluating these limits to make sure they are not prohibitively restrictive to partner needs, while also ensuring that our systems’ performance will not be deteriorated. 

To ensure the reasonableness of these limits, there will be a monitoring period before the throttling occurs during which we will adjust the limits if necessary. During the monitoring period, we will let you know if you would have been significantly throttled, so you can update your application; however, there will likely not be any action required on your part. 

If you would like to take a proactive approach, we will be returning new headers with every response:

Header Semantics
  • UnitStay SOAPAction: number of units that can be requested
  • Other SOAPActions: number of calls that can be made
  • UnitStay SOAPAction: remaining units that can be retrieved during time window
  • Other SOAPActions: remaining calls that can be made during time window
  • Duration of time window, in milliseconds

For example: If a call were to receive a X-RateLimit-Limit header of 5000, a X-RateLimit-Remaining header of 4999, and a X-RateLimit-Window header of 60000, that means that the application could make up to 5,000 calls per minute (since the X-RateLimit-Window value is 60,000 ms = 1 minute). However, since the X-RateLimit-Remaining value is 4999, only 4999 more calls can be made during the minute.

When your application receives a response with a “TooManyRequests” error code, you can optionally implement a retry. Please specify a backoff. In other words, please specify an increasingly long delay between successive retries. A good starting delay value would be the same as the X-RateLimit-Window value.

If you have any other questions or concerns please reach out to our API support team at partnersupport@homeawaysoftware.com.