Error documentation is most useful when it helps readers recover, not just recognize that something failed. Favor concrete payload examples and plain descriptions of what to try next.

Common shape

{
  "error": {
    "code": "invalid_request",
    "message": "The `title` field is required.",
    "request_id": "req_123"
  }
}

The starter reference should eventually call out:

  • authentication failures
  • validation errors
  • rate limits
  • server-side transient failures

Writing guidance

When you document an error code, include:

  1. what triggers it
  2. what fields or headers are involved
  3. what the client should do next

That makes the page useful in production debugging, not just during initial onboarding.