Understand common reasons for error responses
Generally speaking, even beyond Klaviyo, API calls tend to fail for one of 3 reasons:
- Lack of authorization
- Rate limits
- Malformed payloads
Each one of these scenarios will return an error response, and based on the error code, you will need to make specific adjustments. Klaviyo uses conventional HTTP response status codes to indicate success or failure of an API request. Response status codes fall into the following 3 ranges:
- 2xx - Success
- 4xx - Error as a result of information provided as part of the request, a requested object that doesn't exist, an invalid setting, lack of authorization to access object type, etc.
- 5xx - Error due to Klaviyo
401: Not authorized
If you receive a 401 response status code, you do not have adequate authorization for the resource. One cause of this error is using an invalid API key, or missing the API key all together.
- Client-side APIs require a public API key.
- Server-side APIs require a private API key.
Using the wrong API key type will result in an error. Refer to the specified endpoint’s documentation to check which type of API key is required.
429: Rate limit
Klaviyo's APIs employ rate limits against incoming traffic to help maximize system stability. Rate limits for specific endpoints can be found in the API reference for each endpoint. All endpoints are rate limited on a per-account basis. There are 2 ways you can hit a rate limit:
- You hit the burst limit, meaning too many requests per second.
- You hit the steady limit, meaning too many requests per minute.
To find the rate limit for a specific endpoint, refer to the API reference documentation for that endpoint in our Developer Portal. Be sure you are looking at the stable version of the API, as indicated in the upper left-hand corner of the portal.
When you receive a 429 error, you will get a header called Retry-After. This will include an int which indicates the number of seconds before you can start making requests again.
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 some randomness into the backoff schedule to avoid a thundering herd effect.
400: Bad request
If you receive a 400 error code, then one or more identifiers or fields you provided in your payload are invalid. These errors are inherently endpoint-specific. For example, the Get Flows endpoint can only filter based on certain fields, and will return a “400 Bad Request” response if you use a non-supported field or operator. Similarly, passing an invalid identifier for the Create Profiles endpoint, such as misspelling a field (email as emil) will also return a 400.
Avoid rate limit errors by managing request rates
All non-rate-limited 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.
You should treat these limits as maximums, and avoid generating unnecessary load. Learn more about error handling and get a complete list of response status codes on our Developer Portal.