Customer.io Rate Limits

Overview

Understand and implement proper rate limiting and backoff strategies for Customer.io API to handle high-volume operations reliably.

Rate Limit Details

Track API Limits

Endpoint Limit Window

Identify 100 requests/second Per workspace

Track events 100 requests/second Per workspace

Batch operations 100 requests/second Per workspace

App API Limits

Endpoint Limit Window

Transactional email/push 100/second Per workspace

API queries 10/second Per workspace

Instructions

Step 1: Implement Token Bucket Rate Limiter

Build a rate limiter with configurable tokens per second, automatic refill, and async waiting when tokens are depleted.

Step 2: Add Exponential Backoff

Create retry logic with configurable max retries, base delay, max delay, and jitter factor. Skip retries on client errors (4xx except 429).

Step 3: Create Rate-Limited Client

Wrap the Customer.io client to acquire a rate limit token before each request and apply backoff on failures.

Step 4: Handle 429 Response Headers

Parse X-RateLimit-Remaining , X-RateLimit-Reset , and Retry-After headers to adapt dynamically.

Step 5: Add Queue-Based Rate Limiting

Use p-queue with interval-based rate limiting for cleaner high-volume processing.

For detailed implementation code, load the reference guide: Read(${CLAUDE_SKILL_DIR}/references/implementation-guide.md)

Error Handling

Scenario Action

429 received Respect Retry-After header

Burst traffic Use queue with concurrency limit

Sustained high volume Implement sliding window

Resources

• API Rate Limits

• Best Practices

Next Steps

After implementing rate limits, proceed to customerio-security-basics for security best practices.

Prerequisites

• Access to the API environment or API

• Required CLI tools installed and authenticated

• Familiarity with API concepts and terminology

Output

• Configuration files or code changes applied to the project

• Validation report confirming correct implementation

• Summary of changes made and their rationale

See API implementation details for output format specifications.

Examples

Basic usage: Apply customerio rate limits to a standard project setup with default configuration options.

Advanced scenario: Customize customerio rate limits for production environments with multiple constraints and team-specific requirements.