Rate limit headers explanation

Understanding rate limit headers

Every API response includes headers that describe your current rate limit status.

Headers

• X-RateLimit-Limit – Maximum requests allowed per minute (e.g., 100).
• X-RateLimit-Remaining – Requests remaining in the current window (e.g., 87).
• X-RateLimit-Reset – Unix timestamp (seconds since epoch) when the limit resets (e.g., 1746200000).
• Retry-After – (Only on 429 responses) Seconds to wait before retrying.

Example response

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 93
X-RateLimit-Reset: 1746204000

This means: you can make 100 requests per minute. You have 93 remaining. The counter will reset at Unix timestamp 1746204000.

Calculating reset time

const resetDate = new Date(parseInt(response.headers['x-ratelimit-reset']) * 1000);
const secondsToWait = (resetDate - new Date()) / 1000;

Handling 429 responses

When you receive a 429 (Too Many Requests), implement exponential backoff:

async function callWithRetry(url, options, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const response = await fetch(url, options);
    if (response.status !== 429) return response;
    const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i);
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
  }
  throw new Error('Max retries exceeded');
}

Rate limits per endpoint

Rate limits are applied per organization + endpoint type. Example:

• GET /api/trees uses separate counter from POST /api/trees.
• Public endpoints use separate counter (per IP, 30/minute).
• MCP server shares the same counters as REST API (authenticated).

Monitoring your usage

You can view your current rate limit usage in the API dashboard (MCP/API page → 'API usage' tab). Historical usage charts available for Business plan.