Summary

Adds docs/api-development/error-handling.md -- the standard error response format guide for Nerva APIs (issue #56). Every endpoint returns errors as a single top-level error object inside the envelope defined in .claude/pipeline.config.json.

What is covered

• Standard error shape -- { error: { code, message, details, requestId } } with field-by-field rules (stable codes, prose messages, nothing internal leaks)
• Error code registry + constants pattern -- ErrorCodes const object with a derived ErrorCode union type
• Typed error classes -- AppError base plus NotFoundError / ConflictError / UnauthorizedError / ForbiddenError, typed with ContentfulStatusCode so the handler compiles without casts
• Global handling -- app.onError() covering ZodError, AppError, HTTPException (so hono/jwt 401s and bodyLimit 413s do not surface as 500s), and the unexpected-error fallback; app.notFound() for unmatched routes; request-id wiring
• Per-category examples -- validation (400), authentication (401), authorization (403), not found (404), conflict (409), rate limiting (429), server errors (500), each with on-the-wire JSON and security notes (credential disclosure, 404-vs-403 enumeration)
• RFC 9457 Problem Details -- member-by-member mapping table, which principles carry over, where Nerva deliberately diverges (the envelope), and how to emit strict application/problem+json if a consumer requires it
• README updates -- the standards index now shows the nested envelope (it previously showed a flat { error: ..., code: ... } shape), gains the PAYLOAD_TOO_LARGE row, and links the guide from both error-handling sections

Acceptance criteria

• docs/api-development/error-handling.md created
• Standard error response format defined
• Error categories covered: 400 / 401 / 403 / 404 / 429 / 500 (plus 409 and 413 from the existing registry)
• Hono app.onError() global handling shown
• Error code constants pattern included
• RFC 9457 Problem Details referenced
• Linked from docs/api-development/README.md
• CI -- docs-only change; all external links verified returning 200 for the lychee check

Follow-up worth noting

The route-generation and api-validation skills currently emit validation details as { path, message, code }, while the standard (this guide, issue #56, brand-guardian, error-boundary-architect, and the TDD helpers) uses { field, message }. A small follow-up could align those two skills with the documented standard.

Closes #56

🤖 Generated with Claude Code