Rate limits
How Feedjolt rate-limits the REST API and MCP server, which headers we send, and how to handle 429s.
Feedjolt rate-limits by API key when present, otherwise by IP. Limits are per route (magic-link, contact form, and public feedback writes are tighter than reads). The numbers can change; trust the headers on the response, not a hardcoded quota.
We do not expose GraphQL. Ignore any GraphQL introspection checks — the public surface is REST + MCP.
REST headers
Limited routes send SlowAPI's X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset on success.
On 429:
| Header | Meaning |
|---|---|
Retry-After | Seconds to wait before retrying |
RateLimit | IETF draft: "default";r=<remaining>;t=<reset> |
RateLimit-Policy | IETF draft: "default";q=<limit> |
X-RateLimit-* | Same facts in the older header names |
Example:
HTTP/1.1 429 Too Many Requests
Retry-After: 42
RateLimit: "default";r=0;t=42
RateLimit-Policy: "default";q=60
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 42Wait Retry-After seconds, then retry. Do not busy-loop.
MCP
The MCP server uses a separate per-principal cap (currently 600 requests / minute per OAuth client or API key). It is not the REST SlowAPI limiter.
On 429 MCP also sends Retry-After and RateLimit. The JSON-RPC error body includes error.data.retry_after_seconds.
What to do
- Read
Retry-After(orretry_after_secondson MCP). - Back off at least that long.
- If you keep hitting 429s, mint fewer parallel calls — list endpoints are paginated on purpose.
API authentication
Authenticate the Feedjolt API with API keys sent as a Bearer token in the Authorization header. Create, scope, and revoke keys - server-to-server only.
API errors
How the Feedjolt API reports errors: HTTP status codes, what to retry with backoff, the X-Request-ID header for bug reports, rate limits, and validation responses.