homelab-frontend/tasks/4.3-problem-json-errors.md

4.3 — RFC 9457 problem+json rejections (GREEN)

Phase: 4 — Limits and budgets Stage: RED

Every rejection the gateway generates itself must be a machine-readable problem document. Upstream responses are passed through untouched — this covers only errors the gateway originates.

• Every gateway-originated rejection responds with Content-Type: application/problem+json
• The body carries at minimum type, title, status, and detail, and status equals the HTTP status line
• type is a stable, distinct URI per rejection reason, so a client can branch on it without parsing prose
• detail is human-useful and names the offending input where one exists
• Retry-After is set whenever a retry time is knowable — queue full, budget exhausted, upstream saturated
• Retry-After is absent when no retry will help — unknown model, malformed body, oversized body
• No token, credential, header value, or request body content appears in any field
• A rejection is emitted as a structured log line carrying the same reason identifier used in type

Tests come first and must fail because the shape does not exist yet, not because a route is missing.

Verify

curl -s -D - -o /tmp/p.json -X POST localhost:8080/v1/chat/completions \
  -H 'content-type: application/json' -d '{"model":"nope"}' | grep -i content-type
# expected: application/problem+json

python3 -c "import json;d=json.load(open('/tmp/p.json'));assert{'type','title','status','detail'}<=d.keys();assert d['status']==400;print('ok')"
# expected: ok