paperclipai/paperclip · error · ToolGatewayHttpError

gateway_rate_limited

gateway_rate_limited

Error message

MCP gateway request was rate limited

What it means

Gateway protocol rate limiter: the token-bucket keyed by gateway token/actor and action class (session setup vs token requests) was exhausted for the current window, so the MCP protocol request is refused with 429 before handling. Legitimate clients should slow down and honor the reported retry window; sustained trips may indicate a looping client.

Solutions

1. The gateway request hit rate limits. Back off and retry after the window; reduce request frequency.

When it happens

Trigger: Thrown at server/src/services/tool-gateway.ts:3470 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@3f1d897a7c (2026-09-18). Data as JSON: /api/errors/cb36085217438b20. Report an issue: GitHub.

Appendix: source

Thrown at server/src/services/tool-gateway.ts:6605

        ? protocolLimits.sessionSetup
        : protocolLimits.tokenRequests;
    const tokenKey = `mcp_gateway_protocol:token:${session.gatewayTokenId ?? session.actorId ?? "unknown"}:${action}`;
    const tokenState = await consumeProtocolRateLimit({
      companyId: session.companyId,
      counterKey: tokenKey,
      config: tokenLimit,
    });
    if (tokenState.limited) {
      await writeProtocolRateLimitAudit({
        session,
        method,
        limiterKeyClass: "token",
        count: tokenState.count,
        limit: tokenLimit,
        retryAfterMs: tokenState.retryAfterMs,
        clientMetadata,
      });
      throw new ToolGatewayHttpError(
        429,
        "MCP gateway request was rate limited",
        "gateway_rate_limited",
        {
          reasonText:
            "The MCP gateway request was rate limited before the protocol action ran.",
          limiterKeyClass: "token",
          protocolMethod: method,
          retryAfterMs: tokenState.retryAfterMs,
        },
      );
    }

    const gatewayLimit =
      method === "initialize"
        ? protocolLimits.sessionSetup
        : protocolLimits.gatewayRequests;
    const gatewayKey = `mcp_gateway_protocol:gateway:${session.gatewayId ?? session.gatewayPublicId ?? "unknown"}:${action}`;

View on GitHub (pinned to 3f1d897a7c)