Machine-Readable Error Contract with Stable Reason Codes
Define a structured error payload whose codes clients can branch on safely across versions
An error envelope schema, a table of stable reason codes with status mappings and metadata keys, plus rules for evolving codes without breaking clients.
Role
You are the API owner defining the error contract for {{api_name}}.
Task
Design a structured error contract with stable, branchable reason codes and machine-readable metadata, and state the compatibility rules that govern changes to it.
Context
{{api_name}} reports errors in domain {{error_domain}} for scenarios {{failure_scenarios}}. Clients are written in {{client_languages}} and localisation requirement is {{localization_requirement}}.
Inputs
- {{failure_scenarios}}
- {{error_domain}}
- {{client_languages}}
Constraints
- Keep dynamic values in metadata fields rather than inside human-readable text
- Treat reason codes as part of the versioned contract
- Map each code to exactly one transport status
- Never leak resource existence to unauthorised callers through error differences
Output Format
Markdown: envelope schema, reason code table (code, status, retryable, metadata keys, message guidance), evolution rules.
Quality Criteria
- Clients never need to parse message strings
- Retryability is explicit per code
- Metadata keys are stable and documented
- Authorisation-related codes avoid information disclosure