Rate Limits
BrewForge API rate limits (REST 100 requests per hour and 1,000 per 30 days, actions API and MCP 600 per hour and 20,000 per 30 days), rate limit headers and handling 429 responses
The API enforces rate limits to ensure fair usage and service stability.
Limits
All limits are per account (not per token), so several tokens of one account share them. Both windows are sliding:
The REST API and the actions API with the MCP server count separately, each with its own limits:
| Window | REST API (/api/v1/brews, …) | Actions API and MCP server |
|---|---|---|
| Per hour | 100 requests | 600 requests |
| Per 30 days | 1,000 requests | 20,000 requests |
The actions limit is higher because agents make many small calls (look something up, then act). On the MCP server every request counts, including the client listing the tools.
The Calculator API has its own limit per IP address and doesn't count towards these.
Rate Limit Headers
Successful responses and 429 responses include headers showing your current usage:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1706234400000| Header | Description |
|---|---|
X-RateLimit-Limit | Requests allowed in the window: the hourly limit, or the 30-day limit once that one is used up |
X-RateLimit-Remaining | Requests left: the lower of what remains this hour and in the 30 days |
X-RateLimit-Reset | Unix timestamp in milliseconds when the window resets |
429 Too Many Requests
When you exceed a limit:
{
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded",
"details": {
"retryAfter": 45
}
}
}The Retry-After header (and details.retryAfter) tells you how many seconds to wait. The actions API and the MCP server answer in their error format, with the seconds in the message and in details.retry_after_s:
{
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit reached. Try again in 45 seconds.",
"details": { "retry_after_s": 45 }
}
}Both send the header:
HTTP/1.1 429 Too Many Requests
Retry-After: 45Best Practices
- Cache responses - Don't fetch the same data repeatedly
- Use pagination - Fetch only what you need with the
limitparameter (max 100 per page) - Batch operations - Combine multiple updates when possible
- Handle 429s gracefully - Wait for
Retry-After, then implement exponential backoff
Exponential Backoff Example
async function fetchWithRetry(url, options, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
const response = await fetch(url, options);
if (response.status === 429) {
const retryAfter = response.headers.get('Retry-After') || 60;
await new Promise(r => setTimeout(r, retryAfter * 1000));
continue;
}
return response;
}
throw new Error('Max retries exceeded');
}