ADR-0007: RFC 9457 Problem Details for HTTP error bodies¶
- Status: Accepted
- Date: 2026-04-13 (backfill)
- Deciders: @lusoris
- Tags: http, api, errors
Context¶
HTTP error bodies in Go services typically take one of three shapes:
- Bare string:
"invalid input". - Ad-hoc JSON:
{"code": "VALIDATION_ERROR", "message": "..."}. - RFC 9457 Problem Details for HTTP APIs:
application/problem+jsonwithtype,title,status,detail,instance, plus extension fields.
Apps in principles.md §2.5 compliance scope (NIS2, GDPR, BSI C5) are increasingly required to emit machine-readable error envelopes for incident analysis and audit logs. Custom envelopes mean every client (web, mobile, partner, internal) must implement parsing per-app.
Decision¶
We will emit application/problem+json (RFC 9457) for every HTTP error response in framework-provided handlers. core/errors.ProblemFromError and WriteProblem are the single source of truth. Generated ogen handlers funnel errors through ogenkit.ErrorHandler; framework middleware (httpx/middleware/Recover) uses the same encoder on panics.
core/errors.ProblemFromError maps gerr.Code → (status, type-URI, title) so app
code only deals with gerr.Wrap(err, gerr.CodeNotFound). Existing code /
message and ogen error_message fields remain RFC extension members for
wire compatibility. Details and legacy message fields are sanitized for every
5xx status, including coded internal and unavailable errors.
Alternatives considered¶
| Option | Pros | Cons | Why not chosen |
|---|---|---|---|
Ad-hoc {code, message} |
Simple, familiar | Every client re-implements parsing; no standard for extension fields | Standardising on a custom shape costs more than adopting RFC 9457. |
| GraphQL-style error array | Works for batch responses | RFC 9457 already covers single-error case; doesn't apply to REST | Wrong protocol model. |
| Bare HTTP status codes | Minimal | Loses structured detail (which field failed validation, etc.) | Insufficient for compliance audit logs. |
Consequences¶
- Positive: Standard
application/problem+jsonparses with off-the-shelf libraries in every language.typeURI gives an extensible namespace for app-specific error codes (https://golusoris.dev/errors/validation). Audit logs can index bytypefor trend analysis. - Negative: Slightly more verbose than
{code, message}. Apps migrating from existing services must update their clients (one-time cost, documented in migration notes). - Follow-ups: Document the framework's standard
typeURIs indocs/architecture/error-codes.md(TBD, not yet written). Add agerr → ProblemDetailstable toerrors/AGENTS.md.
References¶
- RFC 9457 — Problem Details for HTTP APIs (supersedes RFC 7807).
core/errors.ProblemFromErrorandWriteProblem— canonical implementation.- principles.md §2.6 — adopted wire-protocol standards.