Client errors

A 4xx status means the server understood the request well enough to reject it. The fix usually lives on the client side: URL, headers, body, or permissions.

Common codes you will meet:

• 400 Bad Request: malformed syntax or impossible input.
• 401 Unauthorized: authentication missing or invalid (despite the name, think “unauthenticated”).
• 403 Forbidden: you are known, but not allowed to do this.
• 404 Not Found: no resource at that path.
• 409 Conflict: the request fights current state (duplicate slug, stale version).
• 422 Unprocessable Content: JSON parsed fine but failed business rules.
• 429 Too Many Requests: rate limit hit; back off and retry later.

Good APIs return a body that helps the caller fix the problem. JSON might include an error code, a human message, and field-level details:

{
  "error": "validation_failed",
  "fields": {
    "email": "must be a valid address"
  }
}

HTML sites do the same job with a friendly page instead of JSON.

Be careful what you expose. Public 4xx bodies should not include stack traces, SQL fragments, or internal hostnames. Log the rich detail server-side; give the client enough to correct the request.

Reproduce a few codes:

curl -i https://httpbin.org/status/404
curl -i https://httpbin.org/status/401
curl -i https://httpbin.org/status/429

httpbin returns exactly the status you ask for. The body is short, but the number in the status line is what your client library will surface.

On a real site:

curl -i https://flaviocopes.com/this-page-does-not-exist

You should see 404 in the first line and an HTML error page in the body.

Try this on your own project: trigger one validation error on purpose and read the JSON or HTML your API returns. Ask whether a caller could fix the issue without reading server logs.