examples · errors · 15 / 19

15. 413 - payload over 8 MiB

what this error means

The request body exceeded the per-call cap of 8 MiB. The router rejects oversize bodies at the edge so they never touch the engine. The cap applies to the raw bytes after any compression at the HTTP layer is reversed.

what triggers it

A bulk insert from a file larger than 8 MiB.

POST /v1/tenants/:t/rows/:table/_batch

curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/rows/shop.products/_batch" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @huge-batch.json

the canonical response body

{
  "error": "payload_too_large",
  "message": "request body 12.4 MiB exceeds limit of 8 MiB",
  "retry": false,
  "limit_bytes": 8388608
}

how to recover

Split the batch. The SDKs' insert_many() helpers chunk automatically; if you're calling REST directly, chunk into <= 5 MiB groups.
For ongoing high-throughput ingestion, use the streaming ingest endpoints rather than bulk POSTs.
Trim large blob fields from the row payload - if you're ingesting big binaries, put them in object storage and store a reference key.
retry: false - same body, same limit. Smaller batches will succeed.

common upstream causes

A single batch insert containing every record from a CSV dump.
Rows that include large base64-encoded blobs (images, PDFs).
Wide vector embeddings on many rows (768-dim float32 = 3 KiB per row before JSON overhead).
A debug payload that accidentally inlined a stack trace or a large log fragment.
Forgetting to paginate an upstream source.