paperclipai/paperclip · error

AgentMail response exceeds the processing limit

Error message

AgentMail response exceeds the processing limit

What it means

While streaming an AgentMail API response, the client accumulates chunks and enforces a hard 16 MiB cap on total bytes. Exceeding it throws immediately (the finally clause cancels the reader) to prevent unbounded memory growth from accidental huge responses. This is a self-imposed processing limit, not a provider-reported error.

Solutions

1. Paginate or narrow the AgentMail query (smaller page sizes, date ranges, per-thread fetches) so each response stays under 16 MiB.
2. Request only the fields needed from the API to shrink the payload.
3. If the limit is genuinely too low for your workload, raise the 16 * 1024 * 1024 threshold in the client with awareness of memory cost.
4. Cache/split results across multiple smaller calls instead of one bulk fetch.

Example fix

// before
const all = await api.request("GET", "/v1/threads"); // may exceed 16MiB
// after
const all = [];
let cursor = null;
do {
  const page = await api.request("GET", `/v1/threads?limit=50${cursor ? `&cursor=${cursor}` : ""}`);
  all.push(...page.items);
  cursor = page.nextCursor;
} while (cursor);

// estimate before calling list-style endpoints
if (filters.expectedResultSize > 10_000) {
  throw new Error("Narrow the AgentMail query; response would exceed 16MiB");
}

null

try { return await api.request("GET", path); }
catch (e) {
  if (e.message.includes("exceeds the processing limit")) {
    return fetchInPages(path); // split into paginated calls
  }
  throw e;
}

When it happens

Trigger: An AgentMail endpoint returns a payload larger than 16 MiB — e.g. a thread listing with enormous bodies, an unbounded list call without pagination, or exported attachments embedded in the JSON.

Common situations: Calling a list endpoint without pagination filters on an account with massive history; a bug on the AgentMail side duplicating content; fetching thread contents that include very large HTML/email bodies.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Related errors

• Bridge body exceeded the configured size limit.
• CreateOS process frame is too large.
• dropping 1 event whose serialized envelope exceeds…
• Empty AgentMail response
• github_attachment_canonical_api_too_large

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

Appendix: source

Thrown at server/src/services/agentmail-api.ts:199

        ? seconds * 1000
        : Date.parse(retryAfter ?? "") - Date.now();
      throw new AgentmailApiError(
        response.status,
        Math.max(1000, Math.min(300_000, Number.isFinite(delay) ? delay : 1000)),
      );
    }
    if (response.status === 204) return undefined as T;
    if (!response.body) throw new Error("Empty AgentMail response");
    const reader = response.body.getReader();
    const parts: Uint8Array[] = [];
    let bytes = 0;
    try {
      for (;;) {
        const part = await reader.read();
        if (part.done) break;
        bytes += part.value.length;
        if (bytes > 16 * 1024 * 1024)
          throw new Error("AgentMail response exceeds the processing limit");
        parts.push(part.value);
      }
    } finally {
      await reader.cancel();
    }
    return JSON.parse(Buffer.concat(parts).toString("utf8")) as T;
  }
  const inboxPath = (id: string) => `/inboxes/${encodeURIComponent(id)}`;
  return {
    request,
    whoami: () => request<AgentmailScope>("/auth/me"),
    getInbox: (id: string) => request<AgentmailInbox>(inboxPath(id)),
    listInboxes: () =>
      request<{ inboxes: AgentmailInbox[] }>("/inboxes?limit=100"),
    listDomains: () =>
      request<{ domains: { domain_id: string; domain: string }[] }>(
        "/domains?limit=100",
      ),

View on GitHub (pinned to 3f1d897a7c)