Rate Limiting

The Brandsearch API enforces rate limits and quotas to ensure fair usage. This page explains the limits by tier and how to handle them.

Rate limits by tier

Rate limits are applied per API key. Each tier has different limits across multiple time windows.

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded.",
    "details": {
      "retry_after": 12,
      "window": "1m"
    }
  }
}

Quotas

In addition to rate limits, each API key has daily and monthly request quotas.

Quotas reset automatically — daily quotas reset at midnight UTC, and monthly quotas reset on the 1st of each month.

Quota response headers

Every API response includes headers showing your current quota usage:

Handling rate limits

When you hit a rate limit, the API returns a 429 status with a Retry-After header. The best practice is to implement exponential backoff:

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 = parseInt(response.headers.get('Retry-After') || '1')
      await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000))
      continue
    }

    return response
  }

  throw new Error('Max retries exceeded')
}