{"record":{"id":"48b91f253e5a9305","repo":"paperclipai/paperclip","slug":"agentmail-response-exceeds-the-processing-limit","errorCode":null,"errorMessage":"AgentMail response exceeds the processing limit","messagePattern":"AgentMail response exceeds the processing limit","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/src/services/agentmail-api.ts","lineNumber":199,"sourceCode":"        ? seconds * 1000\n        : Date.parse(retryAfter ?? \"\") - Date.now();\n      throw new AgentmailApiError(\n        response.status,\n        Math.max(1000, Math.min(300_000, Number.isFinite(delay) ? delay : 1000)),\n      );\n    }\n    if (response.status === 204) return undefined as T;\n    if (!response.body) throw new Error(\"Empty AgentMail response\");\n    const reader = response.body.getReader();\n    const parts: Uint8Array[] = [];\n    let bytes = 0;\n    try {\n      for (;;) {\n        const part = await reader.read();\n        if (part.done) break;\n        bytes += part.value.length;\n        if (bytes > 16 * 1024 * 1024)\n          throw new Error(\"AgentMail response exceeds the processing limit\");\n        parts.push(part.value);\n      }\n    } finally {\n      await reader.cancel();\n    }\n    return JSON.parse(Buffer.concat(parts).toString(\"utf8\")) as T;\n  }\n  const inboxPath = (id: string) => `/inboxes/${encodeURIComponent(id)}`;\n  return {\n    request,\n    whoami: () => request<AgentmailScope>(\"/auth/me\"),\n    getInbox: (id: string) => request<AgentmailInbox>(inboxPath(id)),\n    listInboxes: () =>\n      request<{ inboxes: AgentmailInbox[] }>(\"/inboxes?limit=100\"),\n    listDomains: () =>\n      request<{ domains: { domain_id: string; domain: string }[] }>(\n        \"/domains?limit=100\",\n      ),","sourceCodeStart":181,"sourceCodeEnd":217,"githubUrl":"https://github.com/paperclipai/paperclip/blob/3f1d897a7c018d76563a21c6e39c3c9b03933622/server/src/services/agentmail-api.ts#L181-L217","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Paginate or narrow the AgentMail query (smaller page sizes, date ranges, per-thread fetches) so each response stays under 16 MiB.","Request only the fields needed from the API to shrink the payload.","If the limit is genuinely too low for your workload, raise the 16 * 1024 * 1024 threshold in the client with awareness of memory cost.","Cache/split results across multiple smaller calls instead of one bulk fetch."],"exampleFix":"// before\nconst all = await api.request(\"GET\", \"/v1/threads\"); // may exceed 16MiB\n// after\nconst all = [];\nlet cursor = null;\ndo {\n  const page = await api.request(\"GET\", `/v1/threads?limit=50${cursor ? `&cursor=${cursor}` : \"\"}`);\n  all.push(...page.items);\n  cursor = page.nextCursor;\n} while (cursor);","handlingStrategy":"validation","validationCode":"// estimate before calling list-style endpoints\nif (filters.expectedResultSize > 10_000) {\n  throw new Error(\"Narrow the AgentMail query; response would exceed 16MiB\");\n}","typeGuard":"null","tryCatchPattern":"try { return await api.request(\"GET\", path); }\ncatch (e) {\n  if (e.message.includes(\"exceeds the processing limit\")) {\n    return fetchInPages(path); // split into paginated calls\n  }\n  throw e;\n}","preventionTips":["Always paginate list endpoints with explicit limits","Request only needed fields to keep payloads small","Fetch attachments separately, not embedded in listings","Split bulk exports into per-thread or per-date calls"],"tags":["agentmail","payload-size","memory-limit"],"backgroundTag":"payload-too-large","analyzedSha":"3f1d897a7c018d76563a21c6e39c3c9b03933622","analyzedAt":"2026-09-18T08:03:59.046Z","contentChangedAt":"2026-09-18T08:03:59.046Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}