HTTP Client Error Status Codes (4xx)
Guide to 4xx client error responses: when to use 400 vs 401 vs 403 vs 404 vs 429, proper error responses, and user experience.
A guide to the common 4xx client-error status codes: 400, 401, 403, 404, 405, 408, 409, 429 and 431, each with its cause, an example, a response body and notes, plus a standard error-response format and security notes.
Use it when
- You are designing error responses for an API.
- You need to pick between similar 4xx codes.
Watch out for
- Error bodies should be machine-readable but must not leak internal detail or secrets.
- Using one generic 400 for everything loses information that clients and monitors can use.
The data
Client errors
9 rows
| Code | Name | Cause | Example | Response body | Notes | Response headers |
|---|---|---|---|---|---|---|
| 400 | Bad Request | Malformed syntax, invalid request message framing, or deceptive request routing. | Missing required JSON field, invalid JSON syntax, query parameter type mismatch | {"error": "Invalid input", "field": "email", "message": "Email format invalid"} | Server cannot or will not process request due to client error (not server fault) | null |
| 401 | Unauthorized | Request requires user authentication; credentials missing or invalid. | No Authorization header, expired JWT, invalid API key | null | Do not use for missing permissions (use 403); client may retry with credentials | WWW-Authenticate: Bearer realm="api" |
| 403 | Forbidden | Server understood request but refuses to authorize; valid credentials but insufficient permissions. | User role lacks access to admin endpoint, IP blocked, account suspended | {"error": "Access denied", "reason": "insufficient_privileges"} | Never expose why access denied in production (security through obscurity); log details server-side | null |
| 404 | Not Found | Requested resource does not exist on server. | Non-existent URL path, deleted resource, typo in endpoint | null | Do not reveal whether resource exists (prevents user enumeration); return generic message | null |
| 405 | Method Not Allowed | Request method not supported for target resource. | GET on /api/users (expects POST), DELETE on read-only endpoint | null | Include Allow header listing supported methods | Allow: POST, PUT |
| 408 | Request Timeout | Server did not receive complete request in time it was prepared to wait. | Client slow-down; slow POST body upload, client closed connection prematurely | null | May be retried by client with exponential backoff; distinguish from 504 (server timeout) | null |
| 409 | Conflict | Request conflicts with current state of resource; cannot be completed. | Editing stale version (optimistic concurrency), duplicate unique key, file lock conflict | {"error": "Conflict", "detail": "Version mismatch; resource modified by others"} | Include details about conflict in body so client can resolve (e.g., current version) | null |
| 429 | Too Many Requests | User sent too many requests in given time (rate limiting). | Exceeded 100 requests/minute limit, burst limit exceeded | null | Include Retry-After header; implement exponential backoff on client | Retry-After: 60 (seconds) |
| 431 | Request Header Fields Too Large | Server unwilling to process request due to individual header fields too large. | Cookie header exceeds 4KB, extremely long User-Agent, huge custom header | null | Often due to oversized cookies; consider clearing cookies or session reset | null |
Error response format
- Standard fields
- error
- message
- details
- code
- timestamp
- Example
- Error
- invalid_input
- Message
- The provided email address is not valid.
- Field
- Value
- not-an-email
- Documentation url
- https://api.example.com/docs/errors#INVALID_EMAIL
- Security notes
- Never leak internal error messages, stack traces, SQL, file paths, or server configuration in production errors
Fields
The shape of this dataset, read from the data itself: every column, its type and a real value. Agents can use this to plan a query without fetching the whole document.
| Section | Field | Type | Example |
|---|---|---|---|
| client_errors | code | integer | 400 |
| client_errors | name | string | Bad Request |
| client_errors | cause | string | Malformed syntax, invalid request message frami… |
| client_errors | example | string | Missing required JSON field, invalid JSON synta… |
| client_errors | response_body | string | {"error": "Invalid input", "field": "email", "m… |
| client_errors | notes | string | Server cannot or will not process request due t… |
| client_errors | response_headers | string | WWW-Authenticate: Bearer realm="api" |
| error_response_format | * | object | {standard_fields,example,security_notes} |
Fetch the same bytes
The static files contain the same reference rows as the API, with no API rate limit. Live metadata, such as view counts, may differ. Use the API for content negotiation; use the static files for a cacheable snapshot.
curl "https://yjtoon.yunusemrevurgun.com/api/dataset/http-client-error-guide?format=toon"
const res = await fetch( "https://yjtoon.yunusemrevurgun.com/static-data/dataset/http-client-error-guide.toon" ); const toon = await res.text();
Rate limit: 120 requests per minute per IP, no key and no signup. API reference →