# Rate limits

| Limit | Default | Applies to |
|---|---|---|
| Requests | **100 per minute** and **10,000 per day** | each key, sliding windows |
| Requests in flight at once | **25** | each key, per server instance |
| Uploads (photos, logo) in flight at once | **1** | each key, per server instance |
| Webhook replays | **10 per day** | the whole account, per mode |
| Answers about other accounts' creators | **20 per rolling 24 hours** | the whole account |

Defaults can be raised per account — [talk to us](https://docs.creator-guard.com/support/) before a large import. `GET /v1/me` shows the limits in effect for your account (`limits.per_minute`, `limits.per_day`, `limits.duplicate_budget`).

## What counts

- Every request with a valid key counts, whatever its result — also `400`, `403`, `409` and `500`.
- `429` answers, `401` answers and requests refused for [`ip_not_allowed`](https://docs.creator-guard.com/errors/#ip_not_allowed) do not count against the key (`401`s use the [per-IP budget](#requests-without-a-valid-key) instead).
- Windows are sliding: they look back 60 seconds and 24 hours from each request and never reset at a fixed time.

## Headers

Every answer that got past the key, IP, scope and concurrency checks tells you where you stand:

```http
RateLimit-Policy: 100;w=60, 10000;w=86400
RateLimit: limit=100, remaining=97, reset=42
```

`RateLimit` describes the tighter of the two windows: the one that is used up, otherwise the one with fewer requests left. `remaining` already counts the current request; `reset` is the number of seconds until a slot in that window frees up. Slow down as `remaining` approaches 0 instead of waiting for a `429`.

## When you hit a limit

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 42
```

The body is an [error](https://docs.creator-guard.com/errors/) with `code` [`rate_limited`](https://docs.creator-guard.com/errors/#rate_limited). `Retry-After` is the `reset` of the window that is used up (the daily one when both are). Pause the **whole queue** for that long, not just the one request.

## Requests without a valid key

Requests that have no valid key — no `Authorization` header, an unknown, revoked or expired key — as well as `GET /v1/` and paths that do not exist, share a separate budget **per client IP address: 30 per minute**, refilled continuously (one every 2 seconds). Past it, every such request from that address gets [`429 rate_limited`](https://docs.creator-guard.com/errors/#rate_limited) with `Retry-After`, without `RateLimit` headers. Requests with a valid key never use this budget, and a key that was accepted in the last 10 minutes is let through even from an address whose budget is used up; a key never seen before (or not for 10 minutes) from such an address waits like any other request until the budget refills. Like the concurrency limit it is kept per server instance. A correctly configured integration never comes near it; a loop retrying a wrong key does.

## Concurrency

More than 25 requests of one key in flight at the same moment → [`429 concurrency_limited`](https://docs.creator-guard.com/errors/#concurrency_limited) with `Retry-After: 1`. Run at most about 10 requests in parallel and the limit never bites. The limit is kept per server instance; during a release two instances can briefly answer, so do not rely on reaching exactly 25.

Uploads (`POST /v1/leads/{id}/photos`, `PUT /v1/me/logo`) are tighter: **one upload per key at a time**. A second upload of the same key while the first is still running → `429 concurrency_limited` with `Retry-After: 1`, before its body is read. Each server instance also takes only a few uploads of all accounts at once; when they are busy, an upload waits up to 10 seconds before it starts, and past that (or when too many are already waiting) it gets `429 concurrency_limited` with `Retry-After: 2`. Upload photos one after the other.

## Duplicate budget

A [`409 duplicate_other_referrer`](https://docs.creator-guard.com/errors/#duplicate_other_referrer) tells you another account already submitted a creator. So that this cannot be used to test lists of handles against other accounts' creators, the account gets **20 such answers per rolling 24 hours**, counted across all of its keys at the moment we answer, so parallel requests cannot exceed it.

When they are used up, **every request that has to check a handle** — `POST /v1/leads` with an `instagram_handle`, or a `PATCH /v1/leads/{id}` that changes it — answers [`429 duplicate_limit_reached`](https://docs.creator-guard.com/errors/#duplicate_limit_reached), whether that creator is new or taken, so it reveals nothing. `Retry-After` says when the oldest counted answer leaves the window. Requests that check no handle are not affected, and neither is a `POST` whose `external_id` you already used: it returns that lead before any handle check.

## Sending many creators

There is no batch endpoint: one request per creator, with an `Idempotency-Key` and `external_id` each. A steady pace of one request per second stays far below the limits; up to 10 in parallel is fine. For more than 10,000 a day, [talk to us](https://docs.creator-guard.com/support/) first.
