api-error-explainer

A small Node.js / Express utility that converts HTTP status codes into user-friendly error responses with clear solutions and supports app-specific overrides.

Most APIs return errors like:

{ "error": "Not Found" }

This library helps you return responses like:

{ "status": 404, "message": "User not found", "solutions": [ "Check the user ID", "Create a new user" ], "action": "FIX_INPUT", "retryable": false }

So the client knows what to do next.

Install

npm install error-response-kit

Quick Start (Express) import express from "express"; import { attachExplainer } from "error-response-kit";

const app = express(); app.use(express.json()); app.use(attachExplainer());

app.get("/users/:id", (req, res) => { const user = null;

if (!user) { return res.explain(404, "user_not_found"); }

res.json(user); });

app.listen(3000);

Response { "status": 404, "message": "User not found", "solutions": [ "Check the user ID", "Create a new user" ], "action": "FIX_INPUT", "retryable": false }

Direct Usage (without Express) import { explainError } from "error-response-kit";

const error = explainError({ status: 404, reason: "user_not_found" });

console.log(error);

Custom Errors (Overrides)

You can add your own app-specific error explanations.

import { configureErrors } from "error-response-kit";

configureErrors({ 404: { order_not_found: { message: "Order not found", solutions: [ "Check your order ID", "Contact support if the issue persists" ], action: "FIX_INPUT", retryable: false } } });

Then use:

res.explain(404, "order_not_found");

Notes

Call configureErrors() once at app startup

This library is user-centric by design

Logging and debugging are intentionally out of scope

Safe fallbacks are used if an error is not defined

Project Status

🚧 Early version (v0.x)

This package is intentionally minimal. Feedback is welcome on:

API design

Error structure

Naming

Real-world usage

Feel free to open an issue or share suggestions.