API contract pattern
RFC 9457 Problem Details: a useful API error response format
Design application/problem+json responses with stable types, status, title, detail, instance, extensions, and safe machine-readable field errors.
Problem Details gives HTTP APIs a standard error envelope without replacing domain-specific error types. Use a stable type URI as the machine identifier, keep title consistent for that type, put occurrence-specific explanation in detail, and never expose stack traces or secrets.
Treat the complete response as an evidence record: status, headers, provider code, request identifier, method, and raw body. The sequence below separates what the response proves from the checks still needed before a safe retry or code change.
Diagnostic procedure
Work from evidence to recovery.
- 01
Choose a stable type
Use a resolvable documentation URI or about:blank. Do not generate a new type for each occurrence.
- 02
Separate class and occurrence
Title describes the problem class; detail and instance describe this occurrence and may vary.
- 03
Add bounded extensions
Field errors, retry metadata, and trace IDs can be extensions, but avoid exposing internal exception text or confidential identifiers.
{"error":"Something went wrong","code":12}{"type":"https://api.example/problems/out-of-credit","title":"Insufficient credit","status":403,"detail":"Balance is 7; operation needs 12.","instance":"/operations/abc"}Evidence
HTTP 429: A rate, quota, concurrency, or resource lock limit blocked the request.
Retry-After is present; it should take precedence over a guessed delay.
The reported request window has no remaining capacity.
Next checks
01Parse Retry-After as either delta-seconds or an HTTP date before scheduling the next attempt.
No account · no upload · no endpoint calledOpen the full incident decoder and operating notes →
FAQ
Before you ship
Does APITC send this evidence to an API?
No. The matching and calculations in the linked workbench run in the active browser tab.
Should every Problem Details response be retried?
No. Retry behavior depends on the method, idempotency protection, provider instructions, and whether the failure is temporary.
Protocol behavior checked against the RFC 9457 — Problem Details for HTTP APIs. Recheck your pinned provider/API version before production deployment.