Call Restriction Types
The Mimecast API utilizes a variety of protective limits to ensure fair play; one such protection is call rate limiting.
Other protective limits include maximum entry counts, historical date restrictions and maximum request items counts per call. These limits are detailed under their respective endpoint's Description section.
In cases where existing API endpoints may begin to negatively impact the platform, we may introduce additional limits, and will detail those on under the respective endpoint’s Description section.
Rate Limiting Rules
- When a user sends a request to the API, they are allocated a call quota that is used to monitor future requests from that user.
- Users can make requests to the API until the call quota has been exceeded. At which point the user's requests will fail due to rate limiting, until the user's call quota drops below the maximum allowed count.
- To allow continued access to the API, Mimecast additionally applies a reset mechanism that adds allowed requests back into the call quota at defined intervals. At least 1 allowed request is added to the call quota at each rate limit reset interval.
Rate Limiting Response Headers
Each response from the Mimecast API will include HTTP headers indicating the rate limiting status:
| Field | Description |
|---|---|
| X-RateLimit-Limit | The user's call quota - the total number of requests allowed. |
| X-RateLimit-Remaining | The total number of calls remaining in the user's 'bucket' (decreased by at least 1 for each request to the API). |
| X-RateLimit-Reset | The time (in milliseconds) for a request to be added back into the call quota, allowing the user to make a new request. At least 1 request is added back to the call quota at each reset interval. |
Rate Limiting Response codes
Under normal operation, requests to the Mimecast API will return a 200 response code. However in the scenario where the X-RateLimit-Limit value is breached the Mimecast API will return a 429 response code and the requested function will not be executed on the server.
In this scenario your application should not send a request to the API for at least the amount of time defined in the X-RateLimit-Reset response header.