Template · Updated
API error reference template
Developers read error references at the worst possible moment: something failed and they want to know why. A complete, consistent reference turns a support ticket into a two minute fix and keeps integrations from stalling.
Short answer
An API error reference lists every error your API returns with its HTTP status, a plain explanation, the usual causes, and the fix. Show the error response format once at the top, then one entry per code. Developers arrive with an exact error in hand, so make every code searchable and every fix concrete.
When to use this template
Use this template for any product with a public API or webhooks. Put it next to your API reference and link to it from every endpoint page. If your API has many errors, group them by status class (authentication, validation, rate limits, server) with the same entry format throughout. Write entries from real failures: search your support inbox and logs for the errors developers actually hit, and document those first with the fixes that worked.
What goes in it
The error format
Show one example of an error response so developers know where the code and message live.
One entry per error code
The code exactly as returned, the HTTP status, and a one line meaning.
Causes and fixes
The common reasons this error happens and what to change. Concrete beats generic.
Retry guidance
Say whether retrying helps, and how long to wait, especially for rate limits and server errors.
Where to get help
What to include when contacting support: request IDs, timestamps, the endpoint.
The template
Copy it into your help center editor and replace the bracketed parts.
# API errors
Errors return a JSON body:
{"error": {"code": "[code]", "message": "[message]", "request_id": "[id]"}}
## [error_code]
HTTP status: [status]
Meaning: [one line].
Common causes:
- [Cause]
- [Cause]
Fix: [what to change].
Retry: [Yes after N seconds / No].
## [next_error_code]
HTTP status: [status]
Meaning: [...]
Fix: [...]
Retry: [...]
## Contact support
Include the request_id, the endpoint, and the time of the request.Example: two Ledgerloop API errors
## invoice_already_sent
HTTP status: 409
Meaning: the invoice was already sent, so it can't be edited.
Common causes:
- Updating an invoice after calling the send endpoint
- Two requests racing to send the same invoice
Fix: void the invoice and create a new one, or send a credit note.
Retry: No.
## rate_limited
HTTP status: 429
Meaning: too many requests in a short time.
Fix: slow down; the Retry-After header says how many seconds to wait.
Retry: Yes, after the Retry-After delay.Mistakes to avoid
- Documenting only some error codes, so developers hit undocumented ones in production.
- Generic fixes like “check your request”, which help nobody.
- Not saying whether retrying is safe.
- Error codes in the docs that don't match the exact strings the API returns.
- Hiding the error reference far from the endpoint pages that produce the errors.
How to keep this article current
Error references drift whenever the API adds, renames, or retires an error, and mismatched codes are worse than missing ones. usedocs proposes an edit when a merged pull request adds or changes an error the reference documents, and the scheduled check flags codes and statuses in the article that no longer appear in the code. Developers' questions the assistant couldn't answer, like an undocumented error, become gaps with drafted entries.
FAQ
Should every API error be documented?
Yes, every code the API can return. Undocumented errors are the ones that generate tickets.
Where should the error reference live?
Next to the API reference, linked from every endpoint page.
Should the reference say whether to retry?
Yes, for every error. It's the first thing developers need to decide.
How do I keep error codes accurate?
Generate the list from the code where possible, or check it against every release that touches error handling.
Should error messages be in the docs?
Include the code exactly and the message as returned, so searches and assistants can match them.
Should errors be grouped?
Group by type, such as authentication, validation, rate limits, and server errors, with the same entry format in every group.
Should the reference include webhook errors?
Yes, if your webhooks can fail or return errors. Developers debugging webhooks look in the same place.
How do I document errors that are rare?
Briefly, but document them. A one line meaning and fix is enough for a rare error, and far better than nothing.