Skip to content
This repository was archived by the owner on Aug 30, 2026. It is now read-only.
This repository was archived by the owner on Aug 30, 2026. It is now read-only.

API reference promises per-endpoint rate limits but only 5 of 202 pages state one #43

Description

@Tsabary

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:

  1. Extract the (method, path, window, max) tuples from the routers.
  2. Map each to its v7/api-reference/** page.
  3. Insert the existing one-line format directly under the auth line:
    **Rate limit**: N requests per 5 minutes.
  4. 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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions