0029 - Adopt RFC 9457 for HTTP Error Responses

Status

Proposed

Context

Our web application exposes a backend HTTP API that is consumed exclusively by our own frontend. Error responses today (or in the naïve approach) could be defined ad hoc (e.g., { error: "message" } or { code, message }), which is simple in the short term but tends to diverge over time as new teams, features, and error types are introduced. This leads to inconsistent error payloads, custom parsing logic, and additional documentation and maintenance overhead. RFC 9457 ("Problem Details for HTTP APIs") defines a standard JSON (and XML) structure for machine-readable error information in HTTP responses, using the application/problem+json media type. It provides a canonical top-level schema with fields such as type, title, status, detail, and instance, plus arbitrary extension members for domain-specific data. The stated goal is to avoid re-inventing error formats for each API while still supporting application-specific semantics. Although our current API is only used by a single frontend, we value standardization, convention over configuration, and minimizing boilerplate and custom code. We also anticipate increased use of AI tools, code generation, and static analysis that benefit from predictable, documented structures.

Decision

We will adopt RFC 9457 "Problem Details for HTTP APIs" as the standard envelope for all non-2xx HTTP error responses in our web application, serialized as application/problem+json. Concretely: * Every error response will return a JSON object conforming to RFC 9457's "problem details" model, with at least type, title, status, and detail where applicable. * We will define and document a small set of application-specific "problem types" as URIs under our domain (e.g., https://ourapp.example/problems/validation-error) for recurring domain errors. * Additional machine-readable metadata may be added via extension members when needed (e.g., field_errors, correlation IDs, business codes). * Domain error handling inside the codebase should map naturally onto problem details rather than inventing ad hoc serializers per endpoint.

Consequences

Positive: * Error handling becomes standardized, documented, and easier to reason about. * Frontend and future clients can rely on a stable schema for parsing and presenting errors. * We reduce custom code, documentation drift, and integration ambiguity. * AI-assisted tooling and generated clients benefit from a known error contract.

Negative / Trade-offs: * Some initial effort is required to define problem types and refactor existing endpoints. * The structure may feel heavier than minimal ad hoc payloads for very simple internal APIs, but this cost is acceptable in exchange for consistency.