designing-backend-error-messageslisted

Designs backend API error contracts with a REST-default approach using RFC 9457 Problem Details, stable machine-readable codes, retry semantics, validation error payloads, observability, and security-safe messaging. Reviews existing error handling against a binary rubric and proposes concrete fixes. Produces optional artifacts such as errors.yaml entries, Problem Details examples, OpenAPI fragments, and runbook templates. Use when creating or revising backend error responses, auditing API error quality, mapping status/code behavior, or documenting error handling for REST, gRPC, GraphQL, and async services.
msewell/agent-stuff · ★ 0 · API & Backend · score 70

Install: claude install-skill msewell/agent-stuff

# Designing Backend Error Messages Author backend error-message contracts with a REST-first workflow. Switch transport guidance only when the task explicitly targets gRPC, GraphQL, or async/event systems. ## Workflow 1. **Establish scope and transport** - Identify API style: REST (default), gRPC, GraphQL, or async/event. - Identify whether the task is design-from-scratch or refactor/review. 2. **Define the canonical error shape first** - For REST, use `application/problem+json`. - Include these baseline fields: - `type`, `title`, `status`, `code`, `detail`, `trace_id` - Add extensions only when needed: - `errors[]` (validation), `is_transient`, `retry_after_ms`, `help_url`, domain metadata. 3. **Define status-code policy and error-code taxonomy** - Map each failure mode to the most specific status code. - Assign a stable namespaced machine code per failure mode (for example `validation.email.invalid_format`). - Keep code names stable; never rename published codes. 4. **Write user-facing message copy** - Keep `title` stable per error type. - Make `detail` occurrence-specific and actionable. - State the next action clearly: fix request, retry (with timing), or contact support with `trace_id`. 5. **Handle validation and retry semantics explicitly** - Return all field errors in one response. - Use JSON Pointer paths in `errors[].pointer`. - Set retry semantics with `is_transient`; include `Retry-After` / equivalent hints