Rate limits
Request limits and how to handle rate-limit errors.
Use the limits below to plan request volume. Insight and segment-estimate limits apply per credential and operation. Product limits apply per connected store.
| Operation | Limit |
|---|---|
Insights: lifetime value, RFM segments, top products, customers at risk (/v1/insights/*) | 10 requests per second |
Segment size estimate (POST /v1/segments/estimate) | 30 requests per minute |
Product catalog (/v1/commerce/products*) | 5-request burst, then 1 request per second per store, counted only when the live store is called |
Add a list subscriber (POST /v1/list-building/campaigns/{campaign_id}/subscribers) | 60 requests per minute per key |
External pop-up webhook (POST /v1/list-building/webhooks/{list_id}) | 120 requests per minute per List ID |
Messaging send (POST /v1/conversations/{id}/messages, POST /v1/conversations/messages) | 60 requests per minute per key, and 300 per minute for the whole brand, shared by both send routes |
| Other messaging and webhook operations | 30 to 120 requests per minute per key; see the Messaging guide |
List-building API asks have a 30-day cooling period after a decline, expiry or opt-out for the
campaign. They allow one API request per number across the brand's campaigns in a rolling 24 hours
and 5,000 API-sourced optin_requested records per brand in a rolling 24 hours across all keys.
The number cap returns pending when this campaign has an open ask, otherwise refused;
the brand cap returns 429 rate_limited without Retry-After. Pending retries still work.
Keep API keys server-side; never ship them in browser or quiz client code.
See List building for retry-key and START behaviour.
Product requests may also be limited by Shopify.
When you are limited
A limited request gets 429 with the code rate_limited and a Retry-After header in seconds:
HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json
{"error":{"code":"rate_limited","message":"Rate limit exceeded"}}Wait at least Retry-After seconds, then retry. If you run many requests in parallel, spread them out or
add jitter so they do not all retry at once.
The Shopify and Klaviyo tools pass those services' own rate limiting through as 429 rate_limited
without a Retry-After header; the message says how long to wait.
A fixed limit is not a 429. Reaching one, such as the 25 custom providers a brand can have, answers 409
with the code limit_reached, and retrying will not succeed until you remove something.
Over MCP, a limited tool call returns an error result that starts with rate_limited and says how long to
wait.
Collect endpoints
The collect host (https://cdp.vyg.app) applies request limits to the browser ingest and pixel
routes. A request over them gets 429 with the body {"message":"Too Many Requests"} and no
Retry-After header, instead of an error object. Retry with exponential backoff. See
Collect errors.