The gap
v7/api-reference/getting-started.mdx states:
Each endpoint has its own rate limit, applied per project and per IP. When a limit is exceeded, the API returns 429 Too Many Requests. Limits are noted per endpoint in this reference.
That last sentence isn't true. Of 202 pages under v7/api-reference/, 5 actually note a limit:
utils/get-metadata — 30 requests per 5 minutes
storage/fetch-file — 100 per 5 minutes
storage/upload-image — 20 per 5 minutes
- (+2 others)
Every other endpoint leaves the reader to discover its limit by hitting a 429. Rate limits vary a lot in practice — from 5/5min on some writes up to 300/1min on hot reads — so the omission is not cosmetic; an integrator sizing a backfill or a polling loop has nothing to go on.
Why now
Noticed while documenting the POST /reports limit, which changed from 5 to 25 per 5 minutes when that endpoint absorbed chat message reports (sublay-io/server-hosted#109). That one page is now correct; the other ~196 are not.
Suggested fix
The limits are declared in one place server-side — rateLimiter("<window>", <max>) on each route in server/src/v7/routers/*.ts — so this is mechanical rather than investigative:
- Extract the
(method, path, window, max) tuples from the routers.
- Map each to its
v7/api-reference/** page.
- Insert the existing one-line format directly under the auth line:
**Rate limit**: N requests per 5 minutes.
- Flag any endpoint with no page, and any page with no matching route.
Worth considering generating this rather than hand-writing it, so the docs can't drift the next time a limit changes — that drift is exactly what produced this issue.
Alternatively, if per-endpoint limits aren't going to be documented, soften the claim in getting-started so it stops promising something the reference doesn't deliver.
The gap
v7/api-reference/getting-started.mdxstates:That last sentence isn't true. Of 202 pages under
v7/api-reference/, 5 actually note a limit:utils/get-metadata— 30 requests per 5 minutesstorage/fetch-file— 100 per 5 minutesstorage/upload-image— 20 per 5 minutesEvery other endpoint leaves the reader to discover its limit by hitting a
429. Rate limits vary a lot in practice — from 5/5min on some writes up to 300/1min on hot reads — so the omission is not cosmetic; an integrator sizing a backfill or a polling loop has nothing to go on.Why now
Noticed while documenting the
POST /reportslimit, which changed from 5 to 25 per 5 minutes when that endpoint absorbed chat message reports (sublay-io/server-hosted#109). That one page is now correct; the other ~196 are not.Suggested fix
The limits are declared in one place server-side —
rateLimiter("<window>", <max>)on each route inserver/src/v7/routers/*.ts— so this is mechanical rather than investigative:(method, path, window, max)tuples from the routers.v7/api-reference/**page.**Rate limit**: N requests per 5 minutes.Worth considering generating this rather than hand-writing it, so the docs can't drift the next time a limit changes — that drift is exactly what produced this issue.
Alternatively, if per-endpoint limits aren't going to be documented, soften the claim in
getting-startedso it stops promising something the reference doesn't deliver.