| name | klaviyo-rate-limits |
| description | Implement Klaviyo rate limiting, backoff, and request queuing patterns.
Use when handling 429 errors, implementing retry logic,
or optimizing API request throughput for Klaviyo.
Trigger with phrases like "klaviyo rate limit", "klaviyo throttling",
"klaviyo 429", "klaviyo retry", "klaviyo backoff", "klaviyo Retry-After".
|
| allowed-tools | Read, Write, Edit |
| version | 1.7.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","klaviyo","email-marketing","cdp"] |
| compatibility | Designed for Claude Code |
Klaviyo Rate Limits
Overview
Handle Klaviyo's per-account fixed-window rate limits with proper Retry-After header handling, exponential backoff, and request queuing. This skill installs a small set of composable helpers: a retry wrapper that honors Klaviyo's Retry-After, a request queue that paces sustained throughput, a monitor that reads live rate-limit headers, and a rate-aware bulk import.
Prerequisites
- The
klaviyo-api SDK installed in the target project (npm install klaviyo-api).
- The
p-queue package installed for the request queue (npm install p-queue).
- A working knowledge of Klaviyo's dual-window (burst + steady) rate limiting, summarized in the architecture table below.
- Write access to the project's
src/klaviyo/ directory, where the generated helper files land.
Klaviyo Rate Limit Architecture
Klaviyo uses per-account fixed-window rate limiting with two distinct windows:
| Window | Duration | Limit | Description |
|---|
| Burst | 1 second | 75 requests | Short spike protection |
| Steady | 1 minute | 700 requests | Sustained throughput cap |
Both windows apply simultaneously. Exceeding either triggers a 429 Too Many Requests.
Rate Limit Headers
On successful requests:
| Header | Description |
|---|
RateLimit-Limit | Max requests for the window |
RateLimit-Remaining | Remaining requests in window |
RateLimit-Reset | Seconds until window resets |
On 429 responses (different headers!):
| Header | Description |
|---|
Retry-After | Integer seconds to wait before retrying |
When you hit a 429, headers are NOT returned. Only is present.
