EN 
Error messages often frustrate users and AI agents. A good error message helps users get critical information and figure out what to do next. That’s why, error messages are the highest-intent documentation a technical writer publishes. For example, when a user gets an error message such as ERR_TOKEN_EXPIRED, it shows that they are blocked right now and will want to act on it to fix it. Most of the API documentation covers the happy path, and failures usually show up as customer support tickets.
AI agents interact with APIs more often, and they can act on the right things if error messages exactly pinpoint the root cause and advise how to fix the issue. Thus, error messages should be actionable with clear instructions on what to do next. This helps AI agents think about the causes of failure and know how to rectify them. It is thus paramount that technical writers focus on writing clear and helpful error messages and evaluating them before publishing them for a better AI agentic experience.
Why Error Messages, Codes, and Pages Serve Different Roles?
Error messages, error codes, and documentation pages serve different purposes. Technical writers usually write about API documentation covering API endpoints and their workflows. Given that error messages are part of API development, technical writers must collaborate with developers to write a clear error message associated with each error code. Most importantly, additional parameters with textual information can be emitted during an error to inform the human or AI agent about the root cause and remediation process.
An error message shows the product or API failure. It usually covers what went wrong and what to do next. Instead of writing a generic error message that states a reason, technical writers can add more context to the error message. For example: “The API key ending in ‘4f2a’ has read-only access to this project.” This error message gives more information to users and AI agents rather than a “Permission denied” error message. Technical writers and developers should avoid generic text such as “try again later” because it is not actionable.
The error code is the stable identifier behind error messages. Even if the error messages are reworded, the error code does not change. This stable identifier makes it safe for AI agents to search the respective documentation content.
The documentation page for each error message should contain extensive details covering:
- list of causes
- fix for each cause
- proactive steps to prevent this error next time
Technical writers need to cover the entire spectrum of UI features and the functionality of the API to ensure that proper documentation is available for each use case.
How to Structure a Consistent Error Page?
An error page should have a proper structure, and it helps users to navigate to the right section.
It usually contains:
- Start with the error string as the page title: If the API returns
INVALID_API_KEY, that exact string should be the title. This is because users usually copy error messages from the UI or API response and paste them directly into the documentation page - Show the response: This includes the full payload as the API returns it, such as HTTP status, error code, error message and other parameters that are emitted as part of its response
- List the root causes in order of frequency
- Write the fix as numbered steps for each root cause
A familiar structure brings consistency and helps users as they navigate across multiple error pages. It also helps AI agents find the right sections and produce a predictable response.
See how Document360 keeps your API and error documentation in sync
Book a Demo
Keep Error Codes Stable
A stable code is only useful if it remains stable until the product expires. The rules that make this possible are:
- Never reuse a retired error code, as it will keep surfacing in old support tickets after the feature is retired
- Namespace the error code by subsystem. For example,
BILLING_CARD_DECLINEDis more useful thanError 4024
Link Error Codes to Documentation with RFC 9457
Assigning an error code to each error and then linking it to a documentation page is the best practice and it’s exactly what RFC9457 formalizes. RFC 9457 defines the type member as a URI reference that identifies the problem type. An API can use that URI to point to documentation that explains the problem and its resolution.
The following is the process technical writers can follow:
- Derive the page URL from the code such as
/errors/invalid-api-keyso that links can be generated by the system - Return the URL in the error response so that every failure becomes an entry point into your documentation site
- Generate a subpage from the error code registry so that all errors are documented
Start With Your Top 20 Errors
Technical writers need to prioritize the errors that are taxing their users. The best way to scout is to look for support tickets and group them by error string. Technical writers can also look at search keywords from their documentation site search engine and chatbot prompts. By applying the Pareto rule that 80% of issues are caused by 20% of error messages, technical writers can compile the list of pages and error messages they need to fix. Given that AI agents can act on the error messages, it is important to track analytics/metrics on AI agents’ traffic to error messages. This helps to quantify the impact of technical writers’ effort in structuring error codes, error messages, and the respective documentation pages.
