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.

Source

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

      stdio: ["pipe", "pipe", "pipe"],
    });
    let stdout = "";
    let stderr = "";
    let nextId = 1;
    const pending = new Map<number, {
      resolve: (value: unknown) => void;
      reject: (error: Error) => void;
    }>();
    const timer = setTimeout(() => {
      child.kill("SIGTERM");
      for (const { reject } of pending.values()) {
        reject(new ToolGatewayHttpError(504, "Local stdio MCP tool call timed out", "tool_timeout", {
          connectionId: input.connection.id,
          catalogEntryId: input.entry?.id ?? null,
        }));
      }
      pending.clear();
    }, input.timeoutMs);
    timer.unref?.();
    child.stdout.setEncoding("utf8");
    child.stderr.setEncoding("utf8");
    child.stdout.on("data", (chunk: string) => {
      stdout += chunk;
      let newline = stdout.indexOf("\n");
      while (newline >= 0) {
        const line = stdout.slice(0, newline).trim();
        stdout = stdout.slice(newline + 1);
        if (line) {
          try {
            const message = JSON.parse(line) as Record<string, unknown>;
            const id = typeof message.id === "number" ? message.id : null;
            if (id !== null && pending.has(id)) {
              const waiter = pending.get(id)!;
              pending.delete(id);
              if (message.error !== undefined) {
                waiter.reject(stdioProtocolError("Local stdio MCP server returned a JSON-RPC error", {

View on GitHub (pinned to 01ad858492)

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@01ad858492 (2026-08-18). Data as JSON: /api/errors/cb36085217438b20. Report an issue: GitHub.