What should a web framework do with an empty request body, and with extra bytes after a complete parsed value?

## Four states that all look like nothing "Empty body" is not one condition. A framework can face any of these, and conflating them is how a client bug becomes silent data loss: | State | What was sent | Reasonable outcome | |---|---|---| | No body at all | no body bytes, typically no content type either | the argument is absent; an optional argument binds, a required one fails | | Zero-length body with a media type | a content type but no bytes | the parser has nothing to parse — normally a parse failure | | Whitespace only | bytes that contain no value | same as zero-length for structured formats | | An explicit null literal | a complete, valid value that happens to be null | binds a null value, which is *not* the same as absent | The last row is the one people collapse. A body that explicitly says null is a value the client chose to send; a missing body is a client that sent nothing. If both bind the same way, an endpoint can no longer distinguish "clear this field" from "I did not mention this field", which is exactly the distinction a partial-update endpoint depends on. ## Strict or lenient — pick one and mean it Frameworks differ, and both behaviours are defensible in isolation: - **Strict**: an empty body where a value is expected is a parse failure, mapped to **400 Bad Request**. - **Lenient**: the value binds as absent, and the argument's own declaration — optional, defaulted, nullable — decides whether that is acceptable. What is not defensible is applying them inconsistently across a service. The failure mode is specific and expensive: an argument the handler believes is required binds to a default because a parser was lenient, the handler proceeds, and a request that should have been rejected writes plausible-looking wrong data. Whichever policy you adopt, the check "is this value genuinely required?" must exist somewhere explicit — in the binding declaration or in validation — rather than being an emergent property of the parser's mood. Two adjacent points are worth stating because they are commonly muddled: - A request with no body but a route that requires one is a **client** error, so it belongs in the 4xx range, not 5xx. Letting a parse exception escape as a server error misattributes the fault and pollutes error budgets. - A zero-length body still has a media type if the client sent one, and that type is still looked up. So "unsupported media type" and "body was empty" are **different** rejections with different causes — the first is a wrong label, the second is missing content — and reporting both as one status makes them indistinguishable in logs. ## Trailing data after a complete value Most structured text formats define one value per body. A parser that has read a complete value and finds more non-whitespace bytes has two options: 1. **Reject.** The message is not what its format allows; fail with a 400 naming the offset. 2. **Stop at the first value and ignore the rest.** Convenient, and quietly dangerous. Leniency here hides real problems: - a client that **retried inside the same body** and appended a second copy of the payload; - a **truncated-then-resumed** write producing a valid prefix followed by fragments; - an intermediary or buggy serializer **appending** stray bytes; - deliberately appended content that a downstream component might parse differently from yours. In every case the sender and the receiver end up with different beliefs about what the message was, and no error was raised to tell anyone. The general rule is worth keeping: **when two parties can disagree about what a message contained, reject rather than choose.** ## Making the behaviour legible - Report parse failures with the **position** at which parsing gave up, and say whether that position is a byte or character offset; "invalid body" alone costs the client an afternoon. - Distinguish, in the response and in logs, between *unsupported type*, *empty body*, *malformed body* and *trailing data* — they have four different fixes. - Do not repair bodies. Inserting a default for an empty body, or discarding trailing bytes, moves the client's bug into your data. - Make optionality explicit at the handler boundary, so a reader can tell whether an absent body is legal without knowing the parser's configuration. - Test the three empty states separately. A suite that only covers a well-formed body and a malformed one never touches the case that actually ships broken.