Rate Limits

Segment has limits on the number of requests you can issue to the Public API at one time, and calculates these limits based on:

• The sender IP address
• The authentication token
• Complexity and performance requirements of the request

Every successful HTTP response contains the following HTTP headers:

• X-RateLimit-Consumed: the number of requests performed during the current rate limiting window.
• X-RateLimit-Remaining: the number of requests remaining in the current rate limiting window.
• X-RateLimit-Reset: a timestamp, in RFC 5322 format, denoting when the limit will be reset (that is, when a new window will begin).

Rate limited requests fail with the 429 status code. The failure includes a descriptive response which contains metadata about the request limits.

Rate limit error object

The example below shows a response that shows the remaining and consumed points.

{
  "errors": [
    {
      "type": "RequestError",
      "message": "Too many requests",
      "data": {
        "remainingPoints": 0,
        "msBeforeNext": 57647,
        "consumedPoints": 21
      }
    }
  ]
}

The most common causes for rate limits include, but are not limited to:

• Too many requests made against a resource in a short period of time.
• Requesting a large page count or too many pages in a paginated resource too quickly.
• N+1 requests that are issued in a for loop with a large number of elements.
• Programs that restart automatically after crashing.

The Segment Public API includes generous rate limits that allow normal workflows to complete. If you receive rate limit errors, review your requests for places where you can reduce the number of individual calls, and use the best practices listed below to avoid or mitigate rate limit overages.

• Use list-based endpoints whenever possible. Avoid loading multiple hundreds of items using single-resource endpoints. For example, request a batch of Destinations, rather than iterating over a list of single Destinations.
• Consider using exponential backoffs when retrying operations.
• Avoid writing code that invokes the Segment Public API in a for loop. If you must use for loops, consider stopping code execution briefly using sleep calls between items in a list.
• Contact Segment support if you think your workflows are being affected by unreasonable rate limits.