Concepts

Rate limits

Predictable ceilings with honest headers.

Default limits are 600 requests per minute per key with bursts of 100, returned on every response. These numbers are provisional while commercial tiers are finalised.Proposed design

RateLimit-Limit: 600
RateLimit-Remaining: 597
RateLimit-Reset: 42        # seconds
Retry-After: 12            # only on 429

Treat 429s as back-pressure: pause the worker for Retry-After seconds and resume. Idempotency keys make the retry safe.