Rate Limits & Errors

Understanding API rate limits and error handling.

Rate Limits

Each API key has three rate limit counters:

Window	Default Limit
Per Minute	100 requests
Per Hour	5,000 requests
Per Day	100,000 requests

Limits are configurable per API key in agent settings.

Rate Limit Headers

All responses include rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1638360000

Header	Description
X-RateLimit-Limit	Maximum requests allowed
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Unix timestamp when limit resets

Rate Limit Response

When limit exceeded:

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again later.",
  "retryAfter": 45,
  "rateLimits": {
    "requestsPerMinute": 100,
    "requestsPerHour": 5000,
    "requestsPerDay": 100000
  }
}

Status Code: 429 Too Many Requests

Handling Rate Limits

Exponential Backoff

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429) {
        const delay = Math.pow(2, i) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}

Check Headers Before Next Request

function shouldWait(headers) {
  const remaining = parseInt(headers.get('X-RateLimit-Remaining'));
  return remaining < 5; // Wait if < 5 requests left
}

Error Codes

Code	Status	Description	Retry?
400	Bad Request	Invalid request	❌ No
401	Unauthorized	Invalid API key	❌ No
403	Forbidden	Access denied	❌ No
404	Not Found	Resource not found	❌ No
429	Too Many Requests	Rate limit exceeded	✅ Yes
500	Internal Server Error	Server error	✅ Yes
503	Service Unavailable	Service down	✅ Yes