BrewForge Docs

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:

WindowREST API (/api/v1/brews, …)Actions API and MCP server
Per hour100 requests600 requests
Per 30 days1,000 requests20,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
HeaderDescription
X-RateLimit-LimitRequests allowed in the window: the hourly limit, or the 30-day limit once that one is used up
X-RateLimit-RemainingRequests left: the lower of what remains this hour and in the 30 days
X-RateLimit-ResetUnix 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: 45

Best Practices

  1. Cache responses - Don't fetch the same data repeatedly
  2. Use pagination - Fetch only what you need with the limit parameter (max 100 per page)
  3. Batch operations - Combine multiple updates when possible
  4. 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');
}

On this page