payload_too_large

HTTP 413

When this happens

Every /api/v1/* request body is capped at 8,192 bytes (8 KB), checked twice before any handler runs:

• If the request declares a Content-Length header larger than the limit, the request is refused immediately without reading any body bytes.
• Independently, the body is read incrementally and the running byte count is checked as each chunk arrives. The stream is cancelled the instant the total crosses the limit. That is why a missing or understated Content-Length cannot smuggle a larger body past the first check: the second one reads the actual bytes, whatever the header claimed.

The error envelope

{
  "error": {
    "code": "payload_too_large",
    "message": "The request body is too large.",
    "request_id": "req_1a2b3c4d5e6f7a8b9c0d1e2f",
    "docs": "https://canopypay.io/errors/payload_too_large"
  }
}

What to do about it

Reduce the request body. In practice that usually means trimming an oversized metadata object on POST /api/v1/intents. This is a client-side fix; retrying the identical body will fail identically. The bound is fixed for every caller, so a single request cannot ask for a higher limit.