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.
The data
Client errors
| 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
Fetch the same bytes
The static files are identical to what the API returns, but with no rate limit and no server round trip. Use the API when you want a query and a content type; use the files when you want to cache one document.
curl "https://yjtoon.com/api/dataset/http-client-error-guide?format=toon"
const res = await fetch( "https://yjtoon.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 →