Skip to content

Rate Limits

To maintain the performance and stability of our APIs, Keelvar imposes rate limits on the number of requests you can make within a specific time window.

A quota policy is maintained by the server to limit activity of clients. Quota units represent requests made by a client to the endpoint.

The limit for each endpoint is detailed in the specific endpoint API documentation:

It can also be determined from the RateLimit-Limit header that is returned on successful responses.

This API follows the draft Internet Engineering Task Force (IETF) standard: RateLimit header fields for HTTP

Successful Requests

Successful requests will include the rate limit details in the response headers. This is to inform the client of their usage and remaining quota before hitting the limit. The headers are:

  1. RateLimit-Limit: The maximum number of quota units the client is permitted to make in the rate limit window.
  2. RateLimit-Remaining: The number of quota units remaining in the current rate limit window.
  3. RateLimit-Reset: The time remaining in the current rate limit window before resetting, specified in seconds.

Sample HTTP response headers for GET request which includes rate limits:

HTTP/1.1 200 OK
Content-Type: application/json
RateLimit-Limit: 100
RateLimit-Remaining: 95
RateLimit-Reset: 20

In this example:

  • RateLimit-Limit: 100 - Indicates that the client had 100 quota units in the rate limit window.
  • RateLimit-Remaining: 95 - Shows that the client has 95 quota units left in the current rate limit window.
  • RateLimit-Reset: 20 - Indicates the time (in seconds) remaining in the current rate limit window.

Exceeding the limit

A 429 Too Many Requests HTTP status code will be returned when a client exceeds the limit. The response will also include a Retry-After header which shows the number of seconds that the client should wait before retrying the request.

Sample HTTP response when limit is exceeded:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 5
Retry-After: 5

{
  "error": "Rate limit exceeded. Please wait before making further requests."
}