Error System

Error System

Conduit uses a centralized error catalog and encodes errors in all supported formats with a consistent envelope. Each error includes:

• status — HTTP status code
• title — human-readable error category
• message — localized description
• details — optional list of specific error messages
• documentation — link to the error's documentation page

See the Error Catalog for details.

Error Envelope

All errors use the same structured envelope, regardless of output format:

{
  "error": {
    "status": 400,
    "title": "Bad Request",
    "message": "The request could not be processed.",
    "details": ["Missing required field: title"],
    "documentation": "https://conduit.untapped.tech/docs/errors/bad-request"
  }
}

The envelope is encoded into JSON, YAML, XML, TOML, CSV, NDJSON, or CBOR depending on the client's requested format.

Error Catalog

Conduit maintains a centralized catalog of all error types. Each error has:

• a unique title
• a status code
• a documentation slug

Examples include:

• Bad Request
• Unauthorized
• Forbidden
• Not Found
• Conflict
• Unsupported Media Type
• Unprocessable Entity
• Too Many Requests
• Internal Server Error

Each error maps to a documentation page under /docs/errors/<slug>.html.

Multi-Format Encoding

Errors are encoded using the same multi-format engine as normal responses. Supported formats:

• JSON
• YAML
• XML
• TOML
• CSV
• NDJSON
• CBOR

The encoder ensures consistent structure across formats.

Error Writer

Handlers emit errors using a single entry point in the error system. The writer:

• selects the correct error spec
• adds detail messages
• generates the documentation URL
• encodes the envelope

This ensures that all errors—validation, authorization, routing, database—are emitted consistently.

Notes

• All errors use a consistent envelope.
• Documentation URLs are generated from error titles.
• Errors are encoded in the requested output format.
• Handlers use a single error writer for consistency.