httputil/docs/adr/ADR-002-xerrors-to-http-status-mapping.md

ADR-002: xerrors.Code to HTTP Status Mapping

Status: Accepted Date: 2026-03-18

Context

HTTP handlers must translate application errors into appropriate HTTP status codes. Without a shared mapping, each handler or controller does its own ad-hoc conversion, leading to inconsistent status codes across endpoints (e.g. one handler returning 500 for a not-found, another returning 404).

xerrors defines stable Code constants aligned with gRPC canonical status names. The transport layer is responsible for translating those codes to HTTP — this was an explicit decision in xerrors ADR-001.

Decision

Error(w http.ResponseWriter, err error) is the single entry point for writing error responses. It uses errors.As to unwrap *xerrors.Err and reads the Code field. errorCodeToStatus maps each code to an HTTP status:

xerrors.Code	HTTP Status
ErrInvalidInput	400 Bad Request
ErrUnauthorized	401 Unauthorized
ErrPermissionDenied	403 Forbidden
ErrNotFound	404 Not Found
ErrAlreadyExists	409 Conflict
ErrGone	410 Gone
ErrPreconditionFailed	412 Precondition Failed
ErrRateLimited	429 Too Many Requests
ErrInternal	500 Internal Server Error
ErrNotImplemented	501 Not Implemented
ErrUnavailable	503 Service Unavailable
ErrDeadlineExceeded	504 Gateway Timeout
(unknown / nil)	500 Internal Server Error

The JSON response body always has the shape {"code": "...", "message": "..."}. If *xerrors.Err carries context fields (from WithContext), those fields are merged into the top-level response body alongside code and message.

Errors that do not unwrap to *xerrors.Err (plain errors.New, third-party errors) are mapped to 500 with a generic "INTERNAL" code and "internal server error" message. The original error is not exposed to the caller.

Consequences

• All endpoints in a service share the same error shape and status mapping. A NOT_FOUND error always becomes 404, regardless of which handler returns it.
• Business logic selects the appropriate xerrors.Code; the transport layer picks the status code. Neither layer needs to know about the other's mapping.
• The code field in the JSON response is the stable xerrors.Code string value (e.g. "NOT_FOUND"), not an HTTP status integer. Clients can switch on the code string to distinguish cases within the same status class.
• Context fields from xerrors.Err.WithContext are promoted to top-level JSON fields. This means field names must not collide with "code" or "message". This is a caller responsibility, not enforced by the package.
• Unknown or nil errors produce a 500 with no internal detail leaked — defensive by default.