Rate limit headers

Overview

When you exceed a rate limit, the Brevo API returns a 429 Too Many Requests status code along with response headers describing the current rate limit status. Use these headers to monitor API usage and implement retry logic.

Use rate limit headers to:

• Track remaining request capacity
• Determine when rate limits reset
• Implement exponential backoff
• Prevent unnecessary API calls

Rate limit headers

All rate-limited endpoints include the following headers in their responses:

Reading rate limit headers

Limit header

The x-sib-ratelimit-limit header indicates the maximum number of requests you can make in the current time window. This value depends on your account plan and the specific endpoint.

Example:

x-sib-ratelimit-limit: 1000

This means you can make up to 1,000 requests in the current time window.

Remaining header

The x-sib-ratelimit-remaining header shows how many requests you have left before hitting the rate limit. Monitor this value to avoid 429 errors.

Example:

x-sib-ratelimit-remaining: 750

This indicates 750 requests remain in the current time window.

Reset header

The x-sib-ratelimit-reset header specifies when the rate limit counter resets. The value is expressed in the same granularity unit as the rate limit (typically seconds).

Example:

x-sib-ratelimit-reset: 45

This means the rate limit resets in 45 seconds.

Implementing retry logic

Use rate limit headers to implement retry mechanisms:

Check remaining capacity

Before making requests, check the x-sib-ratelimit-remaining header to confirm you have capacity:

1
const response = await fetch('https://api.brevo.com/v3/account', {
2
  headers: { 'api-key': 'YOUR_API_KEY' }
3
});
4
const remaining = parseInt(response.headers.get('x-sib-ratelimit-remaining') || '0', 10);
5
6
if (remaining < 10) {
7
  // Wait before making more requests
8
  await new Promise(resolve => setTimeout(resolve, 60000));
9
}

Handle 429 responses

When you receive a 429 response, read the reset header to determine how long to wait:

1
if (response.status === 429) {
2
  const resetTime = parseInt(response.headers.get('x-sib-ratelimit-reset') || '60', 10);
3
  await new Promise(resolve => setTimeout(resolve, resetTime * 1000));
4
  // Retry the request
5
}

Exponential backoff

Combine rate limit headers with exponential backoff for resilient error handling:

1
async function makeRequestWithBackoff(url, headers, maxRetries = 3) {
2
  for (let attempt = 0; attempt < maxRetries; attempt++) {
3
    const response = await fetch(url, { headers });
4
    
5
    if (response.status === 429) {
6
      const resetTime = parseInt(response.headers.get('x-sib-ratelimit-reset') || '60', 10);
7
      const waitTime = (resetTime + Math.pow(2, attempt) + Math.random()) * 1000;
8
      await new Promise(resolve => setTimeout(resolve, waitTime));
9
      continue;
10
    }
11
    
12
    return response;
13
  }
14
  
15
  throw new Error('Max retries exceeded');
16
}

Best practices

Monitor headers proactively

Check x-sib-ratelimit-remaining before making bulk requests to avoid hitting limits:

1
const remaining = parseInt(response.headers.get('x-sib-ratelimit-remaining') || '0', 10);
2
if (remaining < batchSize) {
3
  // Delay or split the batch
4
}

Cache header values

Rate limit headers are consistent for the same endpoint and account. Cache them to reduce unnecessary API calls when checking limits.

Use webhooks for high-volume operations

For high-volume operations like fetching statistics, use webhooks instead of polling. This reduces API calls and eliminates rate limit concerns.