> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcurrent.ca/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits

> Request limits and how to handle them

All API endpoints are rate limited to **60 requests per minute** per API key.

## Rate limit headers

Every response includes these headers:

| Header                  | Description                              |
| ----------------------- | ---------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed per minute (60) |
| `X-RateLimit-Remaining` | Requests remaining in the current window |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets    |

When you hit the limit, the response is `429 Too Many Requests` with an additional header:

| Header        | Description                     |
| ------------- | ------------------------------- |
| `Retry-After` | Seconds to wait before retrying |

```json theme={null}
{ "error": "Rate limit exceeded. Try again in 60 seconds." }
```

## Handling 429 responses

Use exponential backoff when you receive a 429. The `Retry-After` header tells you the minimum wait time.

<CodeGroup>
  ```python Python theme={null}
  import time
  import requests

  def search_with_retry(name: str, api_key: str, max_retries: int = 3):
      url = "https://api.getcurrent.ca/v1/search"
      headers = {"Authorization": f"Bearer {api_key}"}

      for attempt in range(max_retries):
          response = requests.post(url, headers=headers, json={"name": name})

          if response.status_code == 429:
              retry_after_header = response.headers.get("Retry-After")
              try:
                  retry_after = int(retry_after_header) if retry_after_header is not None else 60
              except (TypeError, ValueError):
                  retry_after = 60
              wait = retry_after * (2 ** attempt)  # exponential backoff
              time.sleep(wait)
              continue

          return response.json()

      raise Exception("Max retries exceeded")
  ```

  ```javascript JavaScript theme={null}
  async function searchWithRetry(name, apiKey, maxRetries = 3) {
    const url = 'https://api.getcurrent.ca/v1/search'

    for (let attempt = 0; attempt < maxRetries; attempt++) {
      const response = await fetch(url, {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${apiKey}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ name }),
      })

      if (response.status === 429) {
        const retryAfter = parseInt(response.headers.get('Retry-After') ?? '60')
        const wait = retryAfter * Math.pow(2, attempt) // exponential backoff
        await new Promise((resolve) => setTimeout(resolve, wait * 1000))
        continue
      }

      return response.json()
    }

    throw new Error('Max retries exceeded')
  }
  ```
</CodeGroup>

## Reducing unnecessary requests

<Tip>
  Searches are saved automatically. Use `GET /search/{id}` to retrieve a
  previous result instead of running a new search. The `searchId` is in every
  response under `meta.searchId`.
</Tip>

If you're building a system that needs to display the same result multiple times (e.g. a dashboard), cache the response locally and use `GET /search/history` to list past searches rather than re-running them.