Your API works on the happy path, but clients struggle when something goes wrong. They get a 200 with an error inside, an HTML page where they expected JSON, a 500 for a typo in a field, or a message that says only "invalid request".
This guide is organised by symptom. For each one you get the likely causes in order of probability, a fix, and a command that confirms the fix worked.
HTTP status codes fall into five classes, as the MDN page on HTTP response status codes lists them: informational (100–199), successful (200–299), redirection (300–399), client error (400–499) and server error (500–599). Most of the problems below come from putting a response in the wrong class.
No version numbers are pinned here, because the guidance applies to the HTTP semantics rather than to one framework. The code is a small Python standard-library server that shows the pattern. Port the pattern to your own framework.
Symptom 1: failures come back as 200 OK, or every error is a 500
What you see: clients cannot tell success from failure without parsing the body. Monitoring shows a flat error rate even though users report failures. Or the opposite: dashboards show many 500 responses caused by bad client input.
Causes, most likely first
- A catch-all handler returns
200with an error payload. The status line is the first thing every client, proxy and monitor reads. A200tells them the request succeeded. MDN defines200 OKas: the request succeeded. - Unhandled exceptions from bad input fall through to the generic
500. A500 Internal Server Erroris a generic message that something unexpected went wrong on the server. Bad client input is not unexpected, so it belongs in the4xxclass. - One status code is reused for every failure. A single
400for a missing token, a missing resource and a server crash removes the information clients need.
Fix: map each failure to the class that owns it.
| Situation | Status |
|---|---|
| Malformed or invalid request, missing or incorrect parameters | 400 Bad Request |
| Missing or invalid credentials | 401 Unauthorized |
| Resource or route does not exist | 404 Not Found |
| Unexpected server fault | 500 Internal Server Error |
| New resource created | 201 Created |
| Success with nothing to return | 204 No Content |
| Received but not yet acted on (batch or background work) | 202 Accepted |
For codes beyond this table, such as 403 or 409, check the MDN status code reference rather than guessing from memory.
Confirm it worked: run the checks in the verification section below. Every failure case must show a 4xx or 5xx status line, never 200.
Symptom 2: clients cannot parse your errors
What you see: client code has a different branch for every endpoint. Some errors arrive as JSON, some as plain text, some as an HTML page from the framework.
Causes, most likely first
- Each handler builds its own error body. Shapes drift over time:
messagehere,msgthere,erroras a string in one place and an object in another. - Framework default error pages leak through. Unmatched routes and unsupported methods often bypass your handlers and return HTML.
- The
Content-Typeheader does not match the body. A JSON body sent astext/htmlmakes strict clients fail even when the JSON is valid.
Fix: define one error envelope and produce it in one function. The shape below is a convention you choose, not something HTTP mandates, so agree on it with your API consumers and document it.
{
"error": {
"status": 400,
"code": "validation_failed",
"message": "The request body is invalid.",
"details": [
{ "field": "email", "issue": "must contain @" }
]
}
}
Keep these properties of the design:
statusrepeats the HTTP status, so a logged body is self-explanatory.codeis a stable, machine-readable string. Clients branch on it, not on the message text.messageis human-readable and may change freely.detailsis always an array, empty when there is nothing to list, so clients never check for its existence.
Route every failure through the same function, including unmatched routes. Always set Content-Type: application/json.
Confirm it worked: request an unknown route and a bad body. Both must return the same envelope with Content-Type: application/json.
Symptom 3: validation errors are vague, late or crash the server
What you see: users get "invalid request" and cannot tell which field failed. Or a malformed body produces a 500 and a stack trace.
Causes, most likely first
- Validation stops at the first problem. The client fixes one field, resubmits, and meets the next error. Collect all problems in one pass.
- The body is parsed before it is checked. Invalid JSON raises an exception that nobody catches, so it surfaces as a
500. MDN describes400as the response for a malformed request, so catch the parse error and return it. - Types are not checked. Code assumes
nameis a string and fails on a number ornull. - Validation lives deep in business logic. By the time it runs, partial work may already have happened. Validate at the edge, before any side effect.
Fix: parse defensively, validate every field, and return all problems in details. The reference server below does this with a 400 and the envelope from Symptom 2.
It also separates two kinds of failure on purpose. Expected client mistakes return 4xx with a specific code. Anything unexpected is caught at the outermost layer, logged on the server, and returned as a 500 with a fixed generic message.
Confirm it worked: send a body with two bad fields. The response must list both in details. Send broken JSON. The response must be a 400, not a 500.
Reference server: one error function, edge validation
Save this as server.py. It uses only the Python standard library, so there is nothing to install. The token YOUR_API_KEY is a placeholder: replace it for any real use, and load it from configuration rather than hard-coding it.
The handler does five things in order: check the route, check credentials, read and parse the body, validate the fields, then create the resource. Each early exit goes through _error, so every failure has the same shape.
import json
from http.server import BaseHTTPRequestHandler, HTTPServer
API_KEY = "YOUR_API_KEY"
class Handler(BaseHTTPRequestHandler):
def _send(self, status, payload):
body = json.dumps(payload).encode("utf-8")
self.send_response(status)
self.send_header("Content-Type", "application/json")
self.send_header("Content-Length", str(len(body)))
self.end_headers()
self.wfile.write(body)
def _error(self, status, code, message, details=None):
self._send(status, {"error": {
"status": status,
"code": code,
"message": message,
"details": details or [],
}})
def do_GET(self):
self._error(404, "not_found", "No such route.")
def do_POST(self):
try:
self._handle_post()
except Exception as exc: # last line of defence
self.log_error("unhandled error: %r", exc)
self._error(500, "internal_error", "Something went wrong on the server.")
def _handle_post(self):
if self.path != "/users":
return self._error(404, "not_found", "No such route.")
if self.headers.get("Authorization") != "Bearer " + API_KEY:
return self._error(401, "unauthorized", "Missing or invalid credentials.")
try:
length = int(self.headers.get("Content-Length", "0"))
data = json.loads(self.rfile.read(length).decode("utf-8"))
except (ValueError, UnicodeDecodeError):
return self._error(400, "invalid_json", "The request body is not valid JSON.")
if not isinstance(data, dict):
return self._error(400, "invalid_body", "The request body must be a JSON object.")
details = []
name = data.get("name")
email = data.get("email")
if not isinstance(name, str) or not name.strip():
details.append({"field": "name", "issue": "required, non-empty string"})
if not isinstance(email, str) or "@" not in email:
details.append({"field": "email", "issue": "must be a string containing @"})
if details:
return self._error(400, "validation_failed", "The request body is invalid.", details)
self._send(201, {"id": 1, "name": name.strip(), "email": email})
if __name__ == "__main__":
HTTPServer(("127.0.0.1", 8000), Handler).serve_forever()
python3 server.py
Verification: prove each fix with curl
Leave the server running and open a second terminal. Each command targets one symptom. The -i flag prints the status line and headers, which is where you confirm the fix.
Success case, expecting 201:
curl -i -X POST http://127.0.0.1:8000/users \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Ada", "email": "ada@example.com"}'
# Two bad fields: expect 400 with two entries in details
curl -i -X POST http://127.0.0.1:8000/users \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": 42, "email": "not-an-email"}'
# Broken JSON: expect 400 invalid_json, not 500
curl -i -X POST http://127.0.0.1:8000/users \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": '
# No credentials: expect 401
curl -i -X POST http://127.0.0.1:8000/users \
-H "Content-Type: application/json" \
-d '{"name": "Ada", "email": "ada@example.com"}'
# Unknown route: expect 404 in the same envelope
curl -i http://127.0.0.1:8000/nothing-here
Symptom 4: clients retry the wrong errors and make outages worse
What you see: after a partial outage, traffic to your API spikes instead of dropping. Logs show the same invalid request repeated many times.
Causes, most likely first
- Clients retry every failure, including
4xx. A400or404will fail again with the same input, so retrying only adds load. The4xxclass means the request itself needs to change. - Retries fire at fixed intervals. Many clients retrying in step hit a recovering server together. Exponential back-off gradually increases the interval between attempts, which eases congestion and avoids making the problem worse.
- No circuit breaker. When an error threshold is reached, a circuit breaker trips and temporarily halts requests to the failing component. That prevents cascading failures and gives the service time to recover.
Fix: your status codes are the signal clients use to decide. Keep client errors in 4xx and server faults in 5xx, then tell client authors to retry only the 5xx class and only with back-off. Retries suit transient network issues and server overload. Add a circuit breaker around calls to a dependency that keeps failing.
The documentation reviewed here does not specify exact retry counts, intervals or breaker thresholds, so pick values from your own traffic and test them under load. If an operation is not safe to repeat, check that your API handles duplicate submissions before you advise clients to retry it.
Confirm it worked: replay a bad request against the server and confirm it returns 400 each time. Then check that your client logs show no retries for 4xx responses and spaced-out retries for 5xx.
Symptom 5: error responses leak internals or help attackers
What you see: error bodies contain stack traces, file paths, SQL fragments or library names.
Causes, most likely first
- The exception message is copied into the response. It is convenient in development and risky in production.
- Debug mode is on in a deployed environment. Frameworks often render detailed pages for unhandled errors.
- Different messages for different auth failures. Telling a caller exactly which part of a credential was wrong helps guessing.
Fix: return a fixed, generic message for every 500, as the reference server does, and log the detail on the server. Keep specifics for 400 validation errors, where the caller needs them to fix the input. Check your framework's documentation for how to turn off debug error pages, since the setting name differs per framework.
Confirm it worked: force an internal error in a test environment, for example by raising an exception inside the handler. The response must contain only the generic internal_error message, while the server log holds the real cause.
Troubleshooting
| Problem | Likely cause | Fix |
|---|---|---|
| A bad request still returns 200 with an error in the body. | A catch-all handler or framework wrapper sets the status after your error function runs. | Set the status line once, in the single error function. Re-run the curl checks with -i and confirm the first line is a 4xx or 5xx status. |
| Broken JSON returns 500 instead of 400. | The parse call is outside the try block, so the exception reaches the outermost handler. | Wrap the read and parse in a try block that catches the parse error and returns 400 with the invalid_json code. |
| An unknown route or unsupported method returns an HTML page. | The framework or server library handles it before your error function. In the reference server, methods without a handler such as PUT use the library default. | Add handlers or a framework-level fallback that routes these cases through the same error function. Check your framework's documentation for the fallback hook. |
| Clients crash reading details on some errors. | details is omitted or null for errors without field problems. | Always return details as an array, empty when there is nothing to list. |
| The server fails to start with an address-in-use error. | Another process is already listening on port 8000. | Stop that process or change the port in the last line of server.py and in the curl commands. |
Frequently asked questions
Should a validation error be 400 or 500?
Use 400. MDN places client errors in the 400 to 499 class, and a 400 means the request is invalid or malformed. A 500 means something unexpected failed on the server, which is not the case for bad input.
What is the difference between 401 and 404?
A 401 means the client lacks valid authentication credentials. A 404 means the requested resource could not be found, often because of a mistyped or outdated URL.
Is there a standard JSON format for error responses?
The HTTP status code reference does not define a body format. Pick one envelope, document it and use it everywhere. The example in this guide is a convention, not a standard.
Which status should I return after creating a resource?
Return 201 Created. MDN describes it as the response after a request succeeded and a new resource was created, typically after POST requests or some PUT requests.
Which errors should clients retry?
Retry transient failures such as server overload or network issues, with exponential back-off. Do not retry 4xx responses unchanged, because the same request will fail again.
What should I do when a request is accepted but processed later?
Use 202 Accepted. MDN describes it as received but not yet acted upon, intended for cases where another process handles the request or for batch processing.
References
From Grokem: https://www.grokem.com/programming/web-development/backend/rest-api-error-handling-fix-wrong-status-codes-messy-error-bodies-and-weak-validation









