Error code: request_body_too_large

What triggers it

The whole request body exceeded the size cap. A payload larger than the endpoint’s maximum (e.g. 16 KiB on enquiries).

Example response

{
  "error": {
    "type": "invalid_request_error",
    "code": "request_body_too_large",
    "message": "The whole request body exceeded the size cap."
  }
}

How to fix it

Reduce the payload; move large content out of the request.

This is deterministic; fix the cause before resending. See the error code catalogue for related codes.

In practice

In a well-built client, request_body_too_large is handled by branching on error.code rather than on the human error.message, which may be reworded over time. The HTTP status (422) gives the broad invalid_request_error class; the code gives the specifics; and, on field errors, error.param pinpoints the input to fix.

This code is deterministic — retrying the identical request reproduces it — so keep it out of your retry path and instead map it to a clear, actionable message. See Map errors to user-facing messages and Read the error envelope for the pattern.