payload_too_large

Each write endpoint enforces a hard cap on the size of the JSON body so a single client can't pin a server with a multi-megabyte payload. The caps are:

The inline-bytes cap is shared by POST /v1/media and the MCP tools that accept content_base64 — see MCP tools §4 for the contract. Note that a request body much over it never reaches the API at all: the serving platform rejects it at ~4.5 MB on the wire with a bare 413 FUNCTION_PAYLOAD_TOO_LARGE carrying no error envelope, so size-check the file before sending rather than reading a missing envelope as an outage.

When you send an Idempotency-Key we additionally cap the total request body at 256 KB by default (sources push this to its own cap) because we have to buffer the body in memory to hash it for replay.

Recovery

1. Trim or chunk the offending field.
2. For long-form transcripts that genuinely don't fit, split them into multiple sources and link them client-side.
3. The 1 MB cap on text sources is a hard product decision; if your workflow needs more, file a feature request — file-ingest sources (with S3 multipart uploads) are the long-term answer.
4. For file bytes over the inline cap, switch to the two-step presigned upload and pass the uploadId — do not retry inline.

The error envelope is the same uniform shape; the message field will hint which field tripped the cap.