problem-details-error-designlisted

# Problem Details Error Design (RFC 9457) ## When to Use This Skill Apply at design time — before a single error response is coded — and when auditing an existing API for inconsistent error shapes. ## 1. Problem Details Shape ```json { "type": "https://api.example.com/problems/order-not-found", "title": "Order Not Found", "status": 404, "detail": "Order ord_9f3c1a was not found or has been deleted.", "instance": "/orders/ord_9f3c1a" } ``` | Field | Required | Notes | |---|---|---| | `type` | Yes | A stable URI that never changes; resolves to human-readable docs | | `title` | Yes | Short, human-readable, consistent for the same `type` | | `status` | Yes | Must match the HTTP response status code | | `detail` | No | Instance-specific, safe to show end-users; never a stack trace | | `instance` | No | URI identifying the specific occurrence — good for log correlation | **Media type:** `Content-Type: application/problem+json` (never `application/json` for errors). ## 2. Type URI Design Rules 1. Use a stable base URL your team controls: `https://api.example.com/problems/` 2. Use kebab-case slugs that name the condition, not the HTTP status: `order-not-found`, `insufficient-inventory`, `rate-limit-exceeded` 3. Never reuse a URI for two different conditions 4. The URI should resolve to documentation — consumers bookmark them ``` https://api.example.com/problems/order-not-found ← correct https://api.example.com/problems/404 ← wrong (status