customerio-rate-limits

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.