HTTP 500 — server error with a useful investigation trail

Environment: Web servers, reverse proxies, API backends and browser clients.

Interpret the response correctly

HTTP 500 means the server encountered a condition preventing it from fulfilling a request. It is a broad server-side result, not a precise diagnosis. A 500 differs from 404 (resource not found), 429 (rate limiting) and 502/503 (often gateway/upstream or service availability problems). A browser fetch() promise can resolve successfully with status 500; callers must inspect response.ok.

Reproduce a safe client response

This local server intentionally sends status 500; it is a simulation, not an example of a real unhandled exception:

from http.server import BaseHTTPRequestHandler, HTTPServer

class Demo(BaseHTTPRequestHandler):
    def do_GET(self):
        self.send_response(500)
        self.send_header("Content-Type", "text/plain; charset=utf-8")
        self.end_headers()
        self.wfile.write(b"Internal failure")

HTTPServer(("127.0.0.1", 8766), Demo).serve_forever()

In a second terminal, run curl -i http://127.0.0.1:8766/. Expected: HTTP/1.0 500 Internal Server Error and a short body. Stop with Ctrl-C. The loopback-only bind keeps this exercise off the public network.

Diagnose the real failing backend

1. Capture timestamp, path, sanitized inputs and a correlation/request ID. Do not log tokens, passwords or personal data.
2. Match the request ID to structured server logs and exception details accessible only to maintainers.
3. Compare the active deployment revision, environment configuration, dependency health, database migrations and resource limits.
4. Reproduce in staging with the same non-sensitive request class; add a regression test around the confirmed failure.
5. Return a stable, non-sensitive error message to clients. Keep stack traces, environment variables and internals out of public responses.

Client behavior and boundaries

A JS client can check if (!response.ok) { /* handle status */ }. Do not automatically retry every POST: an operation may have partially committed before the 500, and blind retries can create duplicates. Use idempotency keys where the application protocol supports them and distinguish transient faults from deterministic application bugs.