Rate limits and error handling

Rate limits

All endpoints are rate limited. Check the response codes for a 429 error, which indicates you have hit a rate limit, and retry requests that exceed the rate limit at a later time. If you consistently hit rate limits, we recommend adjusting your request-rate using an exponential backoff algorithm.

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

Errors

Our API uses conventional HTTP response codes to indicate success or failure of an API request. Errors typically fall into 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

The response of all API errors contain a message parameter which has developer-facing information about why the request failed.

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

Code	Summary	Description
200	OK	The request completed successfully
400	Bad Request	Request is missing or has a bad parameter
400	Not Authorized	Request is missing or has an invalid API key
401	Not Authorized	Key is valid, but account does not have permissions to perform this action
403	Forbidden	Request is missing or has an invalid API key
404	Not Found	The requested resource doesn't exist
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