Skip to content

Add error response standardization guide #56

@PAMulligan

Description

@PAMulligan

Description

Create a guide documenting the standard error response format for Nerva APIs, based on RFC 9457 (Problem Details for HTTP APIs). The pipeline config defines an error envelope, but there's no guide showing how to implement consistent error responses.

Why

Inconsistent error formats are a top complaint from API consumers. A standard format with a dedicated guide ensures every endpoint returns errors in the same shape — making it easier for clients to parse and display errors.

Current State

`pipeline.config.json` defines the envelope:
```json
"envelope": {
"dataField": "data",
"metaField": "meta",
"errorField": "error"
}
```

But no guide explains how to structure error responses within this envelope.

Acceptance Criteria

  • Create `docs/api-development/error-handling.md`
  • Define the standard error response format:
    ```json
    {
    "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
    { "field": "email", "message": "Invalid email format" }
    ]
    }
    }
    ```
  • Cover error categories:
    • Validation errors (400)
    • Authentication errors (401)
    • Authorization errors (403)
    • Not found (404)
    • Rate limiting (429)
    • Server errors (500)
  • Show how to use Hono's `app.onError()` for global error handling
  • Include error code constants pattern
  • Reference RFC 9457 Problem Details
  • Link from `docs/api-development/README.md`
  • CI passes

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions