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

Note for Regulation endpoints: The X-RateLimit-Remaining, X-RateLimit-Consumed, and X-RateLimit-Reset headers are updated to reflect regulation-specific quota limits instead of the global API rate limits. Rate limits are tracked separately based on the regulation type category:

• Segment-only Regulations: DELETE_INTERNAL, SUPPRESS_WITH_DELETE_INTERNAL, SUPPRESS_ONLY, UNSUPPRESS, DELETE_ARCHIVE_ONLY
• Segment & Destination Regulations: DELETE_ONLY, SUPPRESS_WITH_DELETE

The header values correspond to the quota for the category matching your request's regulationType.

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

Some 429 responses also include a Retry-After header, giving the number of whole seconds to wait before retrying. When it is present, prefer it over your own retry schedule — it reflects how long the limit will actually be enforced. Requests rejected because the authentication token itself is rate limited always return Retry-After alongside data.msBeforeNext, but omit the data.remainingPoints and data.consumedPoints fields, since those describe a per-endpoint request quota rather than a token-level limit.

The X-RateLimit-* headers are still present on a token-level 429, but they describe your per-endpoint quota, which is unrelated to why the request was rejected — X-RateLimit-Remaining is typically well above zero on these responses. Use the absence of data.remainingPoints to tell the two apart, and Retry-After to decide when to retry.

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
      }
    }
  ]
}

A token-level rate limit returns the same type and message with msBeforeNext alone, accompanied by a Retry-After header:

{
  "errors": [
    {
      "type": "RequestError",
      "message": "Too many requests",
      "data": {
        "msBeforeNext": 60000
      }
    }
  ]
}

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.
• Honor the Retry-After response header when it is present, and use exponential backoffs when it is not.
• 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.