windsurf-rate-limits
Implement Windsurf rate limiting, backoff, and idempotency patterns.Use when handling rate limit errors, implementing retry logic,or optimizing API request throughput for Windsurf.Trigger with phrases like "windsurf rate limit", "windsurf throttling","windsurf 429", "windsurf retry", "windsurf backoff".
When & Why to Use This Skill
This Claude skill provides robust implementation patterns for Windsurf API rate limiting, backoff strategies, and idempotency. It helps developers build resilient integrations by gracefully handling 429 errors, preventing duplicate requests, and optimizing throughput across different service tiers through production-ready TypeScript examples.
Use Cases
- Implementing exponential backoff with jitter to resolve Windsurf 429 'Too Many Requests' errors while preventing thundering herd problems.
- Using idempotency keys to ensure safe retries for POST requests, preventing the accidental creation of duplicate resources during network failures.
- Optimizing API request throughput by monitoring X-RateLimit headers and dynamically throttling traffic based on remaining quota.
- Managing high-concurrency tasks with queue-based rate limiting to stay within the burst and daily limits of Windsurf Free, Pro, or Enterprise tiers.
| name | windsurf-rate-limits |
|---|---|
| description | | |
| allowed-tools | Read, Write, Edit |
| version | 1.0.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
Windsurf Rate Limits
Overview
Handle Windsurf rate limits gracefully with exponential backoff and idempotency.
Prerequisites
- Windsurf SDK installed
- Understanding of async/await patterns
- Access to rate limit headers
Instructions
Step 1: Understand Rate Limit Tiers
| Tier | Requests/min | Requests/day | Burst |
|---|---|---|---|
| Free | 60 | 1,000 | 10 |
| Pro | 300 | 10,000 | 50 |
| Enterprise | 1,000 | 100,000 | 200 |
Step 2: Implement Exponential Backoff with Jitter
async function withExponentialBackoff<T>(
operation: () => Promise<T>,
config = { maxRetries: 5, baseDelayMs: 1000, maxDelayMs: 32000, jitterMs: 500 }
): Promise<T> {
for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
try {
return await operation();
} catch (error: any) {
if (attempt === config.maxRetries) throw error;
const status = error.status || error.response?.status;
if (status !== 429 && (status < 500 || status >= 600)) throw error;
// Exponential delay with jitter to prevent thundering herd
const exponentialDelay = config.baseDelayMs * Math.pow(2, attempt);
const jitter = Math.random() * config.jitterMs;
const delay = Math.min(exponentialDelay + jitter, config.maxDelayMs);
console.log(`Rate limited. Retrying in ${delay.toFixed(0)}ms...`);
await new Promise(r => setTimeout(r, delay));
}
}
throw new Error('Unreachable');
}
Step 3: Add Idempotency Keys
import { v4 as uuidv4 } from 'uuid';
import crypto from 'crypto';
// Generate deterministic key from operation params (for safe retries)
function generateIdempotencyKey(operation: string, params: Record<string, any>): string {
const data = JSON.stringify({ operation, params });
return crypto.createHash('sha256').update(data).digest('hex');
}
async function idempotentRequest<T>(
client: WindsurfClient,
params: Record<string, any>,
idempotencyKey?: string // Pass existing key for retries
): Promise<T> {
// Use provided key (for retries) or generate deterministic key from params
const key = idempotencyKey || generateIdempotencyKey(params.method || 'POST', params);
return client.request({
...params,
headers: { 'Idempotency-Key': key, ...params.headers },
});
}
Output
- Reliable API calls with automatic retry
- Idempotent requests preventing duplicates
- Rate limit headers properly handled
Error Handling
| Header | Description | Action |
|---|---|---|
| X-RateLimit-Limit | Max requests | Monitor usage |
| X-RateLimit-Remaining | Remaining requests | Throttle if low |
| X-RateLimit-Reset | Reset timestamp | Wait until reset |
| Retry-After | Seconds to wait | Honor this value |
Examples
Queue-Based Rate Limiting
import PQueue from 'p-queue';
const queue = new PQueue({
concurrency: 5,
interval: 1000,
intervalCap: 10,
});
async function queuedRequest<T>(operation: () => Promise<T>): Promise<T> {
return queue.add(operation);
}
Monitor Rate Limit Usage
class RateLimitMonitor {
private remaining: number = 60;
private resetAt: Date = new Date();
updateFromHeaders(headers: Headers) {
this.remaining = parseInt(headers.get('X-RateLimit-Remaining') || '60');
const resetTimestamp = headers.get('X-RateLimit-Reset');
if (resetTimestamp) {
this.resetAt = new Date(parseInt(resetTimestamp) * 1000);
}
}
shouldThrottle(): boolean {
// Only throttle if low remaining AND reset hasn't happened yet
return this.remaining < 5 && new Date() < this.resetAt;
}
getWaitTime(): number {
return Math.max(0, this.resetAt.getTime() - Date.now());
}
}
Resources
Next Steps
For security configuration, see windsurf-security-basics.