UUID Studio

400 Bad Request

The server could not understand the request - it is malformed.

What 400 means

400 means the request itself is broken at a level that prevented the server from processing it: unparseable JSON, a missing required parameter, a header the server cannot make sense of, a value of the wrong basic type. The client must change the request; retrying it unchanged cannot succeed.

It is frequently used as a catch-all for any client-side problem, which makes it less useful than it could be. If the request parsed correctly but failed your validation rules, 422 Unprocessable Entity says so more precisely. If the problem is authentication, 401; authorisation, 403; a rate limit, 429. Reserving 400 for genuinely malformed requests makes your logs and dashboards far more informative.

Whichever you choose, put the specific problem in the response body. A bare 400 with no detail is the least helpful response an API can give, because the client has no way to know which field is wrong.

Common causes of a 400

  • Malformed JSON in the request body - a trailing comma, single quotes, or a truncated payload.
  • A required query parameter or header missing entirely.
  • A value that cannot be coerced to the expected type - text where a number is required.
  • A URL with invalid percent-encoding, or a query string the server cannot parse.
  • A header exceeding the server's size limit, which some servers report as 400 rather than 431.
  • Content-Type absent or mismatched with the actual body format.

How to fix a 400

  • Log and inspect the raw request body - validate it as JSON before assuming your serialiser produced it correctly.
  • Check Content-Type matches the body you are sending.
  • Return the failing field name and reason in the response body so the client can act.
  • Consider whether 401, 403, 404, 422 or 429 describes the failure more precisely.

Should a client retry?

The request is malformed. Retrying it unchanged will fail identically - fix the request.

FAQ

400 or 422 for a validation error?
400 when the request could not be parsed at all; 422 when it parsed fine but failed business or schema rules. Both are defensible for validation, but distinguishing them makes failures much easier to diagnose. Be consistent and document your choice.
Why am I getting a 400 with no explanation?
Many servers return a bare 400 by default. Check the response body, and if it is empty check server-side logs - the parse error is usually recorded there even when it is not returned.
Should a client retry a 400?
No. The request is malformed, so an identical retry gets an identical response. Only retry after changing the request.

Often confused with