Attachment errors
Attachments are base64 in the JSON body, which means every limit is really a limit on the encoded size, and base64 expands by about a third.
| Limit | Value | Applies to |
|---|---|---|
| Per attachment | 10 MB | each file, before encoding |
| Total attachments | 20 MB | the sum across one message |
| Request body | 30 MB | the whole JSON payload, encoded |
| Proxy ceiling | 32 MB | nginx, in front of the app |
Per attachment
{ "status": 400, "title": "Attachment too large",
"detail": "\"invoice.pdf\" exceeds 10 MB cap." }
The filename is quoted back, which is the useful part when a loop is attaching several.
Total across the message
{ "status": 400, "title": "Attachments too large",
"detail": "Attachments total about 24 MB; the cap is 20 MB across all attachments on one message." }
Three legal 9 MB attachments breach this while each is individually fine.
The body ceiling, and why the proxy sits above it
30 MB on the decoded request body, enforced in the application. nginx is configured at 32 MB, deliberately above it.
That ordering is load-bearing. When the proxy limit was the lower of the two,
an oversized send was rejected by nginx as 413 text/html, which a JSON client
cannot parse and which carries no request_id. Now the application answers
first, with a problem document you can read.
What to do about large files
Attach a link, not the file. 20 MB of base64 in a JSON body is slow to build, slow to send and slow to accept, and many receiving servers cap the final message well below our limits anyway, which turns a successful API call into a bounce you have to chase.
There is no upload endpoint and no blob storage: attachments are inline on the send, and nothing else is planned at the moment.