Errium – Intelligent API Error Normalization for FastAPI

Errium is a lightweight, framework-agnostic error normalization and translation middleware for modern APIs. It intercepts uncaught exceptions, HTTP exceptions, and request validation errors, standardizing them into clean, consistent, and frontend-safe JSON responses.

---

⚡ The Problem

Building APIs with modern frameworks (like FastAPI) often yields inconsistent error responses, causing friction for frontend teams:

• Ugly FastAPI Validation Errors: Deeply nested, verbose, and difficult to parse direct Pydantic formats.
• Inconsistent Backend Responses: Uncaught internal exceptions return unhandled stack trace leaks or plain text errors depending on where they occurred.
• Frontend Integration Pain: Frontend engineers are forced to write custom parsers for every microservice, parsing varying response layouts.

🚀 The Solution

Errium provides a unified error classification, normalization, and formatting pipeline:

1. Intelligent Middleware (ErriumMiddleware): Transparently intercepts all request lifecycles.
2. Classification Engine (ClassificationEngine): Dynamically resolves error categories, status codes, and user-facing messages.
3. Beautification & Normalization: Transforms nested, complex errors into flat, friendly key-value details.
4. Environment-Aware Sanitization: Exposes detailed backtrace logs in development and secures system internals in production.

---

🌟 Features

• 🟢 Unified Error Format: Every single API error response uses the exact same structured JSON contract.
• 💅 Validation Beautifier: Automatically maps common validation types (e.g. missing, invalid emails, nulls) into clean, capitalized localized messages.
• 🆔 Trace IDs: Seamlessly correlates client-facing responses with server-side application logs.
• 🛡️ Dev vs. Prod Mode: Exposes traceback objects, raw exception names, and actionable debug hints in development, while sanitizing server details in production.
• 🔌 Extensible Plugin Classifier: Register custom classifiers with sorting priority evaluation.

---

📦 Installation

Install Errium in your virtual environment:

uv pip install errium
# Or using traditional pip
pip install errium

---

🛠️ Usage Example

Integrating Errium into your FastAPI codebase takes less than two lines:

from fastapi import FastAPI
from fastapi.exceptions import RequestValidationError
from errium import ErriumMiddleware
from errium.handlers.validation_handler import validation_exception_handler

app = FastAPI()

# 1. Add Middleware to catch raw & HTTP exceptions
app.add_middleware(ErriumMiddleware)

# 2. Add validation exception handler to capture validation errors
app.add_exception_handler(RequestValidationError, validation_exception_handler)

# Your endpoints go here...

---

🔍 Before vs. After

❌ Before Errium (Ugly FastAPI Validation)

{
  "detail": [
    {
      "type": "missing",
      "loc": [
        "body",
        "password"
      ],
      "msg": "Field required",
      "input": null
    }
  ]
}

After Errium (Cleaned, Beautified Response)

{
  "success": false,
  "status_code": 422,
  "code": "VALIDATION_ERROR",
  "message": "Validation failed.",
  "trace_id": "87b003a8-7c15-4a6c-9c76-a05b22b109e2",
  "timestamp": "2026-05-27T12:00:00Z",
  "details": {
    "password": "Password is required."
  }
}

---

🗺️ Roadmap

Errium is designed framework-agnostically at the core. We are planning the following integrations:

• Flask Adapter Layer
• Django / Ninja Adapter Layer
• Express.js Adapter Layer (JavaScript port)
• AI-Powered Developer Suggestions & Self-Healing Hints