Rate limits

Two stages — one by network origin, one by key — the headers they set, and how to back off.

Every /api/v1 request passes two limiters in order. The first counts by network origin and runs before authentication, so an unauthenticated flood is stopped without a database lookup. The second counts by key, per endpoint, and runs after the key has been verified.

Stage	Counted against	Limit	Window
Network	The calling origin, before authentication	600 requests	60 seconds
Per key — `/auth`	Your key	300 requests	60 seconds
Per key — workspace read	Your key	300 requests	60 seconds
Per key — file listing	Your key	300 requests	60 seconds

Headers

Header	When	Meaning
`RateLimit-Limit`	Whenever the limiter is enforcing	The ceiling for the window.
`RateLimit-Remaining`	Whenever the limiter is enforcing	What is left in this window.
`Retry-After`	On a 429	Seconds to wait. At least 1.

Backing off

Honour Retry-After when it is present. It is computed from the window, not guessed.
Otherwise back off exponentially with jitter. A fixed interval across several clients reconverges into the same spike that caused the limit.
Do not retry inside a request somebody is waiting on. Queue it.
If you are polling, poll less. Six hundred reads a minute is a great deal of polling for data that changes hourly.