Define the problem

Describe the condition that triggers an error, not only a status code and message. An error reference is useful when it tells a developer how to recognize, diagnose and recover from a failure, not when it merely repeats an error code.

Choose a useful model

Show stable response fields, types and the role of request or trace identifiers. Describe status, machine-readable code, human message, likely cause, retry behavior and remediation at the level the API actually guarantees.

Build the workflow

Give a recovery strategy: retry, change input, refresh credentials, wait, contact an administrator or stop. Separate authentication, validation, rate limiting and server failures because their safe recovery strategies are different.

Check the result

Separate validation, authorization, conflict, rate-limit and server failures because their next actions differ. Examples should include the response shape and a realistic correction path so readers can test client behavior before production.

Keep it maintainable

Keep examples consistent with real response fields and casing; developers copy error-handling patterns directly. Keep error documentation connected to implementation tests or schemas where possible; undocumented new codes are a contract change for client teams.

Applied example

Turn “Documenting API errors so developers can recover” into one complete developer task. Use a fictional but realistic resource, such as a report, device or order, and write the shortest path from authentication to a successful result. Include the request, the important response fields, one likely failure and the next action after that failure. The exercise should be executable in principle even if the article does not depend on a live service.

Check the example as if you were building a client from it:

  • Which values must the developer replace?
  • Which identifiers are returned by the server and reused later?
  • What status or field tells the client that the operation succeeded?
  • What should the client do when credentials, input or rate limits fail?

If those answers are scattered across unrelated pages, the documentation may be technically complete but operationally weak. API documentation is successful when a developer can predict the interaction, not merely recognize endpoint names.

Quick editorial checklist

  • Define the problem. Describe the condition that triggers an error, not only a status code and message.
  • Choose a useful model. Show stable response fields, types and the role of request or trace identifiers.
  • Build the workflow. Give a recovery strategy: retry, change input, refresh credentials, wait, contact an administrator or stop.
  • Check the result. Separate validation, authorization, conflict, rate-limit and server failures because their next actions differ.