Rate limits, status codes, and errors

Rate limits

Klaviyo's APIs employ rate limits against bursts of incoming traffic to help maximize its stability. Rate limits for specific endpoints can be found in the API reference for each endpoint.

All new API endpoints are rate limited on a per-account basis, and used a fixed-window rate limiting algorithm with two distinct windows: burst (1-second window) and steady (1-minute window). All API traffic will be subject to these rate limits, and will receive HTTP 429 errors in the event either a burst or steady rate limit is reached.

Unless otherwise documented, all API endpoints use one of the following rate limits:

• S: 3/s burst; 60/m steady
• M: 10/s burst; 150/m steady
• L: 75/s burst; 700/m steady
• XL: 350/s burst; 3500/m steady

All non-rate-limited (i.e. non 429) responses will contain the following HTTP response headers that indicate the state of the steady rate limit window to the client. We recommend using these headers to manage your request rate, especially if you maintain a third-party application that makes requests on behalf of Klaviyo customers:

• RateLimit–Limit: The number of requests allowed per time period
• RateLimit-Remaining: The approximate number of requests remaining within a window
• RateLimit-Reset: Number of seconds remaining before current window resets

Treat these limits as maximums and don’t generate unnecessary load.

We recommend watching for 429 status codes and building in a retry mechanism. The retry mechanism should follow an exponential backoff schedule to reduce request volume when necessary; you should also build in some randomness into the backoff schedule to avoid a thundering herd effect.

📘

Note that the RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers are not returned when you actually hit a HTTP 429 error. When you hit the error, those headers are replaced with a Retry-After header that returns an int indicating the number of seconds before you can start making requests.

Ingestion limits

Klaviyo's event tracking endpoints use ingestion limits to prevent processing delays and service interruptions to the event ingestion pipeline. If you are using a Klaviyo webhook, custom integration, or API implementation, it is important to be aware of the limits on the events you send into Klaviyo. The table below provides some guidance on the maximum sizes for your payload and its fields.

Endpoints with ingestion limits:

• /api/events
• /client/events
• legacy /api/track

Response status codes

Our API uses conventional HTTP response status codes to indicate success or failure of an API request. Response status codes typically fall into the following three ranges:

• 2xx - Success
• 4xx - Error as a result of information provided as part of the request, such as a requested object that doesn't exist, an invalid setting, etc.
• 5xx - Error due to Klaviyo

See the table below for a list of error codes and their corresponding descriptions:

Errors

When a request is unsuccessful, the response will include a list of errors, nested under an errors field in the response. Within the error object, the title field includes developer-facing information about why the request failed.

Here is an example of an error response returned for an invalid request to GET /api/events?fields[profile]=email&include=profiless with an invalid include query parameter provided. There’s a typo there! It should be include=profiles not include=profiless.

{
   "errors": [
       {
           "id": "2c76424d-b1ff-4afd-a2a1-728d85dac775",
           "status": 400,
           "code": "invalid",
           "title": "Invalid input.",
           "detail": "'profiless' is not an allowed include parameter for this resource.",
           "source": {
               "parameter": "include"
           },
           "meta": {}
       }
   ]
}