Rate Limits

The AIclicks API rate-limits per API key on a fixed 60-second window. The default ceiling is 60 requests per minute per key.

JWT (dashboard session) callers are not rate-limited — only ak_ API keys are.

Reading your current state

Every response from an API-key caller includes three rate-limit headers:

You can also poll GET /validate — its data.rate_limit field returns the same numbers in JSON:

{
  "rate_limit": {
    "limit_per_minute": 60,
    "remaining": 58,
    "reset_at": 1718531412
  }
}

When you hit the limit

Exceeding the limit returns 429 Too Many Requests with a Retry-After header:

HTTP/1.1 429 Too Many Requests
Retry-After: 23
Content-Type: application/json

{ "detail": "Too many requests. Please try again later." }

Retry-After is in seconds — wait at least that long before retrying.

Best practices

1. Watch X-RateLimit-Remaining and slow down before hitting zero, rather than relying on 429.
2. Respect Retry-After exactly — fixed-interval retries will hit the same wall.
3. Cache on your side. The server-side 1-hour cache only helps when query params match byte-for-byte. Local caching is what protects against hot loops.
4. Stagger key usage. If you have multiple keys, distribute traffic across them — the bucket is keyed on the API key, not the team.
5. Use exponential backoff for 5xx, fixed Retry-After for 429. Don't conflate them.

What counts as one request

Every HTTP call to /api/v1/* increments the counter, including:

• Cache hits (X-Cache: HIT).
• /validate calls.
• 4xx error responses.

5xx responses do not count — server errors are not held against the caller.