Skip to content

Grokem · https://www.grokem.com/programming/web-development/backend/rest-api-error-handling-fix-wrong-status-codes-messy-error-bodies-and-weak-validation

BackendTroubleshooting guide

REST API error handling: fix wrong status codes, messy error bodies and weak validation

Fix the usual REST API error problems: 200 responses that hide failures, 500s for client mistakes, inconsistent error bodies and vague validation. Each symptom lists causes by probability, a fix and a check you can run.

Krishna Sharma

Technical Writer

Published
  • 11 min read
  • 0 sec

Tested with
  • Python
  • curl
  • HTTP
  • JSON
Your progress
  1. REST API error handling: fix wrong status codes, messy error bodies and weak validation11 min(finished)
    0%

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

  1. A catch-all handler returns 200 with an error payload. The status line is the first thing every client, proxy and monitor reads. A 200 tells them the request succeeded. MDN defines 200 OK as: the request succeeded.
  2. Unhandled exceptions from bad input fall through to the generic 500. A 500 Internal Server Error is a generic message that something unexpected went wrong on the server. Bad client input is not unexpected, so it belongs in the 4xx class.
  3. One status code is reused for every failure. A single 400 for 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.

RequestRouteexists?Credentialsvalid?Body parsesand validates?Handlerruns201 Createdsuccessnononounexpectedexception404 Not Found401 Unauthorized400 Bad Request500 InternalServer ErrorSingle error envelope:status, code, message, details
Each check maps to one status, and every failure shares one envelope.

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

  1. Each handler builds its own error body. Shapes drift over time: message here, msg there, error as a string in one place and an object in another.
  2. Framework default error pages leak through. Unmatched routes and unsupported methods often bypass your handlers and return HTML.
  3. The Content-Type header does not match the body. A JSON body sent as text/html makes 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.

json
{
  "error": {
    "status": 400,
    "code": "validation_failed",
    "message": "The request body is invalid.",
    "details": [
      { "field": "email", "issue": "must contain @" }
    ]
  }
}

Keep these properties of the design:

  • status repeats the HTTP status, so a logged body is self-explanatory.
  • code is a stable, machine-readable string. Clients branch on it, not on the message text.
  • message is human-readable and may change freely.
  • details is 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

  1. Validation stops at the first problem. The client fixes one field, resubmits, and meets the next error. Collect all problems in one pass.
  2. The body is parsed before it is checked. Invalid JSON raises an exception that nobody catches, so it surfaces as a 500. MDN describes 400 as the response for a malformed request, so catch the parse error and return it.
  3. Types are not checked. Code assumes name is a string and fails on a number or null.
  4. 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.

python
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()
bash
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:

bash
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"}'
bash
# 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

  1. Clients retry every failure, including 4xx. A 400 or 404 will fail again with the same input, so retrying only adds load. The 4xx class means the request itself needs to change.
  2. 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.
  3. 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

  1. The exception message is copied into the response. It is convenient in development and risky in production.
  2. Debug mode is on in a deployed environment. Frameworks often render detailed pages for unhandled errors.
  3. 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

ProblemLikely causeFix
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

Finished this article?

How did this strike you?

Be the first to react – it is anonymous.

Community

Questions about this?

Ask in Questions and help and get help from other readers.

Ask a questionBrowse Questions and help

Comments

No comments yet. Share what worked for you, or ask a question.

Keep learning

Picked for this article

Related reading, discussions and learning paths on the same subject.

All in Backend

From the community

Learning paths

Learning pathIntermediate

Building and calling APIs

Design an HTTP API people can rely on, read its status codes, choose between REST, GraphQL and gRPC, receive webhooks safely and call a paginated API with retries.

5 lessonsabout 50 minStart

Learning pathBeginner

Infrastructure basics for data work

The ground a data project stands on: the command line, how a name finds a server, packaging an app in a container, where files and databases live, keeping secrets out of code, backups you have tested and a cloud bill you control.

7 lessonsabout 15 minStart

Choose what we may use. You can change this at any time with “Privacy choices” at the foot of every page. Details are in the Cookie policy and the Privacy policy.

Strictly necessary

Remembers your theme, the lessons you marked as done and this choice. It stays on your device, tracks nothing and cannot be switched off.

Always on
What exactly is collected, and why

Google Analytics

Collects
The pages you view, your device and browser type, your language, how you reached the site and your approximate location (country and city, worked out from your IP address).
Why
To understand which pages and lessons are used, so we can improve them.
Stored
Two cookies, _ga and _ga_<id>, for up to 2 years. Google acts for us; the data is processed by Google, including outside your country.

Grokem’s own counts

Collects
The pages you open and how long you stay, how far you scroll, where you came from, your device type, browser, screen size, language and time zone. Your IP address is turned into a code that changes every day; it is never stored as it is.
Why
To see how long lessons are read and where readers leave. Not shared with anyone.
Stored
A random visitor ID, a visit ID and the time of your last page view in your browser’s storage (gr_vid, gr_sid, gr_last). No name or email is attached.