error-envelope-design

What problem does it solve?

It prevents inconsistent API error shapes that cause clients to mis-handle retries, hide root causes, and break batch/multi-resource error semantics.

Core Features & Use Cases

• Choose the correct envelope per transport: HTTP problem+json, GraphQL unions/error extensions, or gRPC google.rpc.Status with typed details.
• Define retry and partial-failure contracts: transient vs non-transient behavior, plus per-item error patterns for batch endpoints.
• Create and centralize an error-code registry: stable, append-only dotted lowercase codes with centralized status/code mapping.
• Require evidence and verification: blocks completion when sample responses, registry locations, schema/proto/OpenAPI proof, or command/receipt evidence is missing.

Quick Start

Ask your AI tool to design a single, consistent error envelope and error-code registry for your new or drifted API, using evidence from existing endpoints and the project’s transport defaults.