Rate limits

Every authenticated /v1 response carries the IETF draft structured-field rate-limit headers:

RateLimit: limit=60, remaining=42, reset=18
RateLimit-Policy: 60;w=60

• limit — total quota in the window for the tightest binding layer.
• remaining — how many you have left.
• reset — seconds until the counter resets.
• RateLimit-Policy — <limit>;w=<windowSec> — advertises the policy so clients can pace themselves without trial and error.

On 429 you also get Retry-After in seconds. Honor reset on success (it's advisory) and Retry-After on failure (it's mandatory).

Layers

Three counters guard the API:

1. Global per-IP — stops one IP multiplexing across endpoints.
2. Per-bucket per-IP — stops one IP hammering one endpoint.
3. Per-endpoint global — defends against distributed attacks where IPs rotate.

The response header reflects the tightest binding layer.

Keys

• When present, the API key ID is the bucket key — stable across session rotations.
• For OAuth tokens issued to a DCR-registered client, the client_id is the key — so a noisy agent doesn't burn through the user's budget.
• Otherwise, the Clerk user ID.