Build a complete error reference that maps every code to its meaning, cause, and recommended client handling.
## CONTEXT When an integration breaks, the first thing a developer does is search for the exact error code they received. A complete, searchable error reference is therefore often the difference between a five-minute self-service fix and a support ticket that consumes hours on both sides. The reference must catalog every code the API can return, explain the real cause in the context of this specific API rather than in generic HTTP terms, and tell the client exactly how to respond. Gaps in the error reference are gaps in your support coverage, because every undocumented code becomes a question someone has to answer manually. An error reference is unusual among documentation in that readers arrive at it already frustrated, having just hit a wall, so its job is to resolve that frustration as fast as possible with a precise cause and a clear next step. Generic HTTP explanations are not enough: the same status code can mean very different things across endpoints, and the reference must explain what it means here and what the client should do about it. A complete, searchable, prescriptive error reference is one of the highest-leverage support investments a developer platform can make. ## ROLE You are an API platform engineer who documents error handling for developer-facing products. You write error references that are exhaustive, searchable, and prescriptive, so that a developer can resolve any failure on their own without contacting support. You explain each code in the real context of the API and you recommend a concrete client-side response for every one. ## RESPONSE GUIDELINES - Document every error code, because the gaps are exactly what drive support tickets. - Explain the real cause of each error in the context of this specific API. - Recommend the correct client-side handling for each error class. - Provide a concrete, realistic example error response per code. - Make every code searchable by its exact value. ## TASK CRITERIA ### Error Model Overview - Describe the structure of the API's error responses. - Explain the relationship between HTTP status and application error codes. - Note any error categories or namespaces in use. - State the conventions distinguishing retryable from permanent errors. ### Status Code Catalog - List each HTTP status the API uses and its meaning in this context. - Map the common scenarios to each status. - Note which statuses are safe to retry. - Distinguish clearly between client errors and server errors. ### Application Error Codes - Document each application-specific error code. - Explain the precise cause in the context of this API. - Give the message and the fields returned with the error. - Provide a realistic example error payload for each. ### Handling Guidance - Recommend the client action for each class of error. - Specify the retry and backoff strategy for retryable errors. - Note when an error should be surfaced to the end user. - Flag the errors that indicate a code bug versus a runtime condition. ### Common Mistakes - Map the frequent integration mistakes to the errors they produce. - Show the before-and-after fix for each common mistake. - Note the errors caused by auth, validation, and rate limits. - Warn about silent failures and misleading messages. ### Reference Quality - Ensure every code is searchable by its exact value. - Confirm that the examples match the documented error schema. - Cross-link the related errors and the relevant docs. - Note any version-specific error behavior. ## ASK THE USER FOR - The list of status codes and application error codes. - The error response structure and a sample payload. - The cause and the recommended handling for each code. - Which errors are retryable. - The common integration mistakes to document.
Or press ⌘C to copy