Error Handling & Problem Responses

A central registry maps failure types to HTTP statuses in one place: the framework catches whatever a handler throws, looks up the closest registered type, and runs that mapper to build the response. Route code stays free of transport concerns.

Once the status line and headers are flushed to the socket, nothing can retract them; HTTP has no take-back. A mapper running afterwards can only append to the body, emit a trailer, log the failure, or abort the connection.

Two rendering modes of one fallback, chosen by a flag, not by the failure. Development mode prints the failure type, message and stack for the author; production mode prints a status and short message so internals never reach untrusted callers.

Most frameworks resolve by specificity: they walk the thrown type's ancestry and pick the nearest registered ancestor, so a subtype registration beats a base-type one. Where the registry is a scanned list of predicates, the first match wins and registration order decides.

A single factory is the only place that can guarantee every failure leaves with the same fields, a correlation id and no internal detail. Per-handler bodies drift as soon as a second person adds an endpoint under time pressure.

Authentication runs first in a pre-handler stage, authorization next, existence last inside the handler after the lookup. The earliest stage to refuse writes the response, so an anonymous request for a missing record answers 401, not 404.

The catch-all is now the nearest registered ancestor for failures the framework raises itself, which already carried their own status. Instead of reaching the built-in mapping, they hit the catch-all and become 500. Fix by narrowing it or honouring a carried status.

Those failures are raised before handler invocation, so no handler code runs and the framework renders its own built-in body. Fix it by attaching the framework's central failure hook to the same factory, wrapping pre-handler failures like thrown ones.

Text chosen from the mapped error code, not the exception's own message. The factory should default to a generic message for anything unrecognised, and send the exception text and stack to the log record keyed by the same correlation id.

Make it where both facts are known: in the handler, after the record loads and the visibility rule runs. A pre-handler hook cannot mask what it never loaded, and rewriting every refusal into 404 over-masks failures unrelated to hidden records.

It depends where the credential check is mounted. Mounted globally, ahead of route resolution, it answers 401 for any path; attached per route, it never runs for an unregistered path and the built-in not-found response wins.

Most frameworks answer 405 Method Not Allowed, because the router can see the path is registered under other methods. Some answer 404 instead, either because method and path form one lookup key or to avoid confirming that the path exists.

Scopes nest: the innermost registry that covers the failing route is consulted first, and a failure with no match there falls through outward to the global one. Rethrowing from a mapper typically resumes that outward fall-through.

Read it from request-scoped context. A parameter works but puts the burden back on every call site, which is the drift the factory exists to remove. The factory must also define what it does when that context is empty.

Authorize first for anything a stranger can reach. A validation error returned before the rights check hands an unauthorized caller your field names, accepted values and sometimes which identifiers exist; validating first only buys a friendlier error.

Do not end it cleanly. Abort so the body stops short of its declared length or terminator — the one incompleteness a receiver can detect — and record the failure server-side. A trailer or agreed end marker is extra.

Stop relying on response status: the committed status is what gets recorded, so a half-sent success logs as a success. Emit a dedicated counter, mark the record post-commit, and set a correlation header before the first flush.

A custom fallback covers only failures that reach the framework. Requests rejected by a proxy in front or by the host server's parser, and failures raised inside the fallback itself, are answered by a different layer.

Treat it as buying error fidelity with memory. Buffer anything small and bounded so late failures still map to a real status; stream only where size or duration forces it, under a completeness contract.

Centralise the vocabulary, distribute the membership. Define a small shared set of failure categories with one status each in a central registry, and let each module map its own failure types onto those categories rather than onto statuses directly.

Split the failure value from its rendering. One factory produces a format-agnostic failure value; a renderer chosen per surface serializes it into that surface's standard. Handlers raise failures and never learn which surface they are serving.

Write the order down as a contract - credential, then rights, then existence - settle credentials once at a shared edge, and verify every endpoint against it. The one service that answers differently becomes the enumeration oracle.

Decide one baseline - terse by default, detail only on explicit opt-in, full failure in the log - then make it an inherited default rather than a rule teams must remember, and verify it by probing every deployed environment.