Klaviyo: API revisions and rate-limit windows
How explicit API revisions and separate burst/steady limits affect a Klaviyo client’s retry, scheduling and compatibility decisions.
- Endpoint + revision
- Burst and steady windows
- Classified outcome
Investigation question
What makes a Klaviyo request reproducible over time? The URL alone is insufficient when an API revision selects behavior and endpoint-specific windows control throughput. This investigation treats version selection and request scheduling as parts of the contract.
Observed
Klaviyo publishes dated API revisions and endpoint-specific rate limits. Its rate-limit guide describes separate burst and steady windows, measured over one second and one minute, and HTTP 429 when a limit is reached. New API endpoints are documented as account-scoped for this limiting behavior. The public changelog gives version changes a visible history. A client that records its chosen revision can associate behavior with a particular contract instead of attributing every difference to the same timeless API. That is different from merely storing the SDK package version.
Inferred
A request can fit a minute’s average budget and still exceed a short burst window. Conversely, spreading a burst does not guarantee that sustained traffic fits the longer window. Separate jobs that share an account can consume the same capacity even if each job appears modest in isolation. Retries also need classification. A temporary capacity response and an invalid request body are not the same problem. Retrying an unchanged invalid body faster will not repair it. A client should retain enough response context to distinguish throttling, validation, authentication and server failures without logging credentials or personal payloads.
Unknown & limitations
No marketing message was sent, profile was changed or account limit was exercised. The public guide does not establish a universal quota for every endpoint, and this article does not infer one. Account-specific limits, exact retry timing and revision-specific payload changes need the corresponding endpoint reference. Examples describe a client design and test strategy, not a measured production workload.
Domain & data models
Illustrative scheduling example: a worker sends many requests at the start of each minute, then remains idle. Its average can look acceptable while the first second exceeds a burst allowance. Smoothing dispatch changes the burst profile; it does not increase the published account allowance. The example intentionally uses no hard-coded Klaviyo quota because tiers vary by operation.
Workflows & state machines
A useful client record includes the endpoint, selected revision, operation identity and outcome category. On a capacity response, honor the documented retry guidance and coordinate workers sharing that account. On a revision upgrade, replay a small set of representative, authorized test requests and compare response shapes before expanding traffic. A focused compatibility check should inspect fields that the application actually uses, not only whether a request returns 200. A successful response with a changed optional field can still alter downstream behavior. Preserve the old and new expected shapes as test fixtures with all customer data removed.