api-error-responseslisted

# API error responses An error response is an API for failure. Clients branch on it, dashboards aggregate it, and support debugs with it; design it with the same care as the success path. ## Method 1. **Adopt problem+json (RFC 9457) as the single shape.** `{"type": "https://api.example.com/errors/insufficient-funds", "title": "Insufficient funds", "status": 402, "detail": "...", "instance": "/orders/123"}` plus your extensions. One shape for every error from every endpoint, including your gateway and framework defaults; the client's error handler should never need a second parser. 2. **Give every error a stable machine code.** `type` (or a `code` extension: `order_not_found`, `rate_limited`) is the branching key; `title`/`detail` are prose you may reword freely. Clients matching on message strings is a contract you created by not providing codes. 3. **Signal retryability explicitly.** 429 and 503 carry Retry-After; include a boolean extension (`"retryable": true`) so clients need no status-code folklore. Wrong retryability signals become either give-up bugs or retry storms (see timeouts-and-retries). 4. **Structure validation failures per field.** An `errors` array of `{field, code, message}` covering all failures at once (see request-validation); UIs map them to inputs, and one round trip replaces five. 5. **Correlate everything.** Every response (success too) carries a request id header; errors echo it in the body. The clie