Coding
AI Prompt for API Error Catalogs
Document every API error with this AI prompt: consistent error catalog with codes, causes, examples and the exact recovery action for callers.
The prompt
Role: You are a technical writer creating the definitive error catalog for an API.
Context: API: [API_NAME]. Error format: [ERROR_FORMAT, e.g. {code, message, details}].
Errors to document:
[ERROR_LIST: status code + code string + when it occurs]
Task: 1) Create the error catalog: for each error — code, HTTP status, plain-English meaning, common causes (2-3), full example response body, and EXACTLY what the caller should do (retry? fix request? contact support?). 2) Add retry guidance: which errors are retryable, with backoff recommendations. 3) Add a troubleshooting flow: "if you get X, check Y first."
Format: Summary table first (code | status | retryable | one-line meaning), then detailed sections per error, then retry guidance, then the troubleshooting flow.
Ask the AI to add a decision tree for the three most common errors: a short 'if you see X, check Y, then Z' flow. Integrators debug faster with a path to follow than with a list to scan.
Constraints: Every error gets a caller action — "something went wrong" is not documentation. Distinguish caller-fixable errors from provider-side errors clearly.
Variables to fill in
Replace each [variable] in the prompt with your own details:
[API_NAME] [ERROR_FORMAT] [ERROR_LIST]
Example input
API=payment API, ERRORS=400 validation, 401/403 auth, 404 not found, 409 conflict, 429 rate limit, 500 internal, FORMAT=Markdown table + per-error detail
How to use this prompt
List every status code your API actually returns — completeness matters more than prose here. For each, state the caller's correct next action.
Tips for the best results
- The 'what the caller should do' column is the whole value — never skip it.
- Ask for the retryable/non-retryable classification; integrators get this wrong constantly.
- Link each error to the endpoint docs where it can occur.
Frequently asked questions
Does it invent error codes?
It documents the contract your code implements; feed it the actual error-throwing code so nothing is invented.
Should I document internal error codes too?
Only the ones callers can receive. Internal codes leak implementation details and confuse integrators — keep them in your runbooks, not the public catalog.