Rate limits
The per-token window, per-person usage limits and edge limits, and how to handle a 429.
Per token
Each personal access token has a window of N requests a minute, with N chosen when the token is created (30, 60, 120 or 300; 120 by default). Every request a token makes costs one, whatever the route and whatever it does: one MCP message is one request, and saving ten sources through MCP or moving 500 sources is still one.
Every token response carries:
x-ratelimit-limit: 120
x-ratelimit-remaining: 115Over the limit, the answer is 429 rate_limited with Retry-After (seconds until the
window turns, 1–60). A refused request is not counted.
Per person
Some actions also spend the person's own usage windows, whatever the credential:
saving sources (sources_per_hour, sources_per_day), resolving URL metadata,
uploading, archiving. Those answer the same 429 rate_limited with details naming
the limit. The archive quota has no Retry-After: it frees up when archives are
deleted.
At the edge
Additional limits may apply in front of the API, whatever the credential. A 429 from
the edge may not carry the JSON envelope.
Handling a 429
Branch on the HTTP status first, then read Retry-After when it is present and wait
that many seconds. Only then look for the JSON error body.
Sessions and Supabase access tokens
The per-token window is the limit you can plan against. A session (cookie) or a Supabase access token has no per-token window, since it is a person using the app; it is bounded by the per-person limits.