Rate limits, status codes, and errors

Rate limits

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:

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

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 guidance on the maximum sizes for your payload and its fields.

Endpoints with ingestion limits:

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

Category	Limit
Max payload size	5 MB decompressed
Max number of event properties per data packet	300
Max size of any field	100 kB
Max number of items in arrays	4000
Max levels of nested objects	10
Timestamp of events	Between 2000 and “now”+1 year

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:

Code	Summary	Description
200	OK	The request completed successfully.
201	Created	The request succeeded, and a new resource was created as a result.
202	Accepted	The request has been received but not yet acted upon. We return this status code for requests that were accepted but are processed asynchronously.
204	No Content	The request succeeded, but the API doesn’t provide a response body.
400	Bad Request	Request is missing a required parameter or has an invalid parameter.
401	Not Authorized	Request is lacking required authentication information. Please follow [the guidance here] (https://developers.klaviyo.com/en/reference/api_overview#authentication) for more details on authenticating your API requests.
403	Forbidden	The request contains valid authentication information, but does not have permissions to perform the specified action. See API key scopes for more information.
404	Not Found	The requested resource doesn't exist.
405	Method not Allowed	The requested resource doesn't support the provided HTTP method, e.g. `DELETE`.
409	Conflict	The request conflicts with the current state of the server.
410	Gone	The requested content has been permanently deleted from Klaviyo’s server. This status code will occur for requested endpoints that no longer exist in our API.
415	Unsupported Media Type	The `Content-Type` or `Content-Encoding` header is set incorrectly.
429	Rate Limit	You hit the rate limit for this endpoint (different endpoints have different rate limits).
500	Server Error	Something is wrong on Klaviyo's end.
503	Service Unavailable	Something is wrong on Klaviyo’s end leading to service unavailability. Check Klaviyo’s Status for updates.

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": {}
       }
   ]
}