Glossary Term
HTTP Error Handling
Learn HTTP error handling best practices for detecting, managing, and responding to errors gracefully. Understand status codes, retry logic, and user feedback.
TL;DR: HTTP error handling is the discipline of turning failures into clear protocol signals and usable client behavior instead of vague breakage.
Good error handling is not just “returning an error message.” It means making the status code, headers, body, retry behavior, and user experience all tell the same story.
What Good Error Handling Actually Means
At a minimum, a good HTTP error flow should answer:
- did the client send something invalid
- did authentication or authorization fail
- is the problem temporary
- should the client retry, redirect, fix input, or stop
If the response does not make that clear, the client has to guess.
The First Split: 4xx vs 5xx
- 4xx means the request cannot succeed as sent in the current client context
- 5xx means the request was reasonable, but the server or one of its dependencies failed anyway
That distinction drives almost everything else:
- who owns the fix
- whether retry makes sense
- what message the UI should show
- what your logs and alerts should mean
Error Bodies Should Help, Not Fight The Protocol
The worst pattern is a mismatch between protocol and payload.
Bad:
HTTP/1.1 200 OK
{"error":"validation failed"}Better:
HTTP/1.1 422 Unprocessable Entity
{"error":"validation_failed","fields":{"email":"invalid"}}The second example gives both humans and clients something reliable to work with.
Retry Logic Needs Intention
Not every failure deserves a retry.
- validation errors usually should not retry
- expired auth may need re-authentication, not blind repetition
502,503, and504may justify retries with backoff429should be handled with rate-limit awareness, often usingRetry-After
That is why error handling is part protocol design and part product behavior.
User-Facing Behavior Still Matters
Good systems translate protocol failures into useful UX:
401: take the user to login and preserve return path404: show recovery links, not a dead end500: acknowledge failure without blaming the user- network failure: offer retry or offline guidance
The protocol should help the product behave calmly under failure, not just satisfy the backend.
Related: Status Code • Response • Request
Frequently Asked Questions
How should APIs handle errors?
Use honest status codes, keep error payloads consistent, and return enough detail for the client to react without exposing internals unnecessarily.
What should an error response include?
A strong error response usually includes the status code, a stable error type or code, a readable message, and any actionable validation or retry details.
Should I use 200 with error in body?
No. Returning 200 for a failed operation makes clients, caches, logs, and observability harder to trust.
How do I handle errors in fetch?
Check `response.ok` or `response.status`. `fetch()` only rejects automatically for network failures, not for 4xx or 5xx responses.