# X_MCP_RATE_LIMITED

## Means

the caller has spent its allowance for this request's class

## Typical cause

more than `rateLimits.read` or `rateLimits.write` requests in one minute from one actor, metered by `mcpHttpRoute` after the body is parsed (the class comes out of the body) and before the tool runs. 429 with `Retry-After`; the bucket key names the actor and never reaches the caller. It has its own code rather than reusing `X_RATE_LIMITED` because the KNOB differs — the HTTP pipeline's buckets do not govern this route, so raising them would run and change nothing

## Fix

wait out the `Retry-After`, or raise it where the route is built: `mcpHttpRoute({ rateLimits: { read: <n>, write: <n> } })`, or `defineAppMcp({ rateLimits })`. Behind N replicas pass `rateLimitStore: postgresRateLimitStore({ executor })` too, or each enforces the full allowance on its own

[MCP and AI](/error-codes#mcp-and-ai)