Skip to main content

Rate Limits & Errors

Understanding API rate limits and error handling.

Rate Limits​

Each API key has three independent rate-limit counters. The defaults are conservative so unattended keys can't run away with usage; you can raise them per-key up to the maximums below.

WindowDefaultMax configurable
Per minute10100
Per hour1001,000
Per day1,00010,000

Limits are configured per API key in your agent's settings.

Rate Limit Response​

When any counter is exceeded, the API returns 429 Too Many Requests:

{
"error": "Rate limit exceeded",
"message": "Too many requests. Please try again later.",
"rateLimits": {
"requestsPerMinute": 10,
"requestsPerHour": 100,
"requestsPerDay": 1000
}
}

The rateLimits object contains the limits configured on the key that triggered the 429 — useful for surfacing to users or logs.

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;
}
}
}

Smooth out request bursts​

If you have bursty traffic, prefer queuing client-side over retrying 429s. A small in-process queue that paces requests to a safe fraction of your per-minute limit is cheaper than backoff loops.

Error Codes​

CodeStatusDescriptionRetry?
400Bad RequestInvalid requestNo
401UnauthorizedInvalid API keyNo
403ForbiddenAccess deniedNo
404Not FoundResource not foundNo
429Too Many RequestsRate limit exceededYes
500Internal Server ErrorServer errorYes
503Service UnavailableService downYes