2026-09-18 · 6 min read · Rahul Chitturi
- api
- problem-details
- http
Problem Details gives HTTP APIs a common error object with members such as type, title, status, detail, and instance. It reduces one-off envelopes, but clients still fail when a proxy changes the status, a server returns the wrong media type, or extensions drift between endpoints.
The HTTP status line remains authoritative transport information. A body status member can help diagnostics, but conflicting values indicate a broken response path rather than a choice for the client to guess.
Validate the response as a whole
Capture the status line, Content-Type, headers, and body together. Confirm application/problem+json is emitted for JSON problem details and that type and instance identifiers are valid under the API's contract.
- Use a stable type identifier for a stable problem category.
- Keep title concise and consistent for that category.
- Treat detail as occurrence-specific human text.
- Namespace and document machine-readable extensions.
Keep clients tolerant but observable
Clients should preserve unknown extensions and fall back gracefully when a response is not Problem Details. They should not branch on localized title or detail text when a stable type or extension exists.
Gateways and exception middleware need tests for errors they generate themselves. Otherwise, upstream services may be consistent while authentication failures, limits, and timeouts use unrelated envelopes.
Exercise failure paths intentionally
Use the JSON formatter for synthetic bodies, URL tool for type and instance identifiers, timestamp converter for retry metadata, and diff for contract revisions.
Test validation failures, authentication, authorization, missing resources, conflicts, limits, upstream timeouts, malformed bodies, empty responses, HTML gateway errors, unknown extensions, localization, and status mismatches.