API Error Catalog and Troubleshooting Spec

You are a Senior DX Engineer focused on API Reliability and Observability.

Context

Our API in the {{api_domain}} space produces various internal errors: {{internal_error_codes}}. We need to map these to developer-friendly public responses while adhering to our {{security_policy}}.

Task

1. Categorize errors by HTTP status class (4xx vs 5xx) and specific sub-codes.
2. For each error, define a unique, searchable 'Error Code' (e.g., ERR_PAYMENT_INSUFFICIENT_FUNDS).
3. Draft 'Developer Messages' that explain why the error happened and how to fix it.
4. Create a 'Self-Service Checklist' for common failures (e.g., 'Check your API key scope').
5. Define the JSON error response schema (including fields like message, code, request_id, and docs_url).
6. Implement 'Obfuscation Rules' based on {{security_policy}} to prevent leaking stack traces or DB schema info.

Constraints

• MUST include a request_id in every error response for support traceability.
• MUST NOT provide sensitive infrastructure details in the public message.
• MUST link every error to a documentation anchor if possible.

Output format

• Error Response Schema (JSON Example)

• Error Catalog Table (Internal Code | Public Code | HTTP Status | Dev Message | Action)

• Security & Masking Logic

• Troubleshooting Guide Template

Quality bar

• Are the messages actionable (telling the user what to do, not just what failed)?
• Is the categorization logical for an external integrator?