@particle-academy/fancy-http-errors
Turn any error response into one sentence for the UI: the Fancy error envelope, FastAPI details and 422 lists, Laravel validation, or an HTML proxy page, never echoing 5xx text. Field errors, retry-after and the request id come out in one shape. Zero runtime dependencies, no React.
npm install @particle-academy/fancy-http-errorsAPI surface
Headless package — drive it from code or an agent. No component grid.
@particle-academy/fancy-http-errors
Turn any HTTP error response into one safe sentence for the UI.
import { normaliseResponse, normaliseFailure } from "@particle-academy/fancy-http-errors";
try {
const res = await fetch("/api/invites", { method: "POST", body });
const error = await normaliseResponse(res); // null on a 2xx/3xx
if (error) {
toast(error.sentence); // "This request is 12.4 MB, over this endpoint's limit of 10 MB."
form.setErrors(error.fields); // { "items.3.price": "This must be a finite number." }
}
} catch (e) {
toast(normaliseFailure(e).sentence); // "We could not reach the server. ..."
}
It reads the Fancy error envelope (from particle-academy/fancy-http-guard
for Laravel and fancy-http-guard for FastAPI/Starlette), and also what servers
send without it:
| Server sent | You get |
|---|---|
{error, message, field?, errors?, limit?, retryAfter?, requestId} |
the code, the sentence, the fields |
FastAPI {"detail": "..."} |
that sentence |
FastAPI {"detail": [{loc, msg}]} (422) |
dotted fields, "2 fields need attention." |
Laravel {"message", "errors": {field: [...]}} |
the first message per field |
| an nginx/Cloudflare HTML page, plain text, nothing | the sentence for the status |
Retry-After: 30 or an HTTP-date |
retryAfter and "Try again in 30 seconds." |
For agents. This package is not listed on the Fancy MCP catalog server yet. The server,
https://ui.particle.academy/mcp(streamable HTTP, no API key; MCP idfancy-ui), lists the released Fancy packages with install commands and docs. How an agent installs and uses this package is in AGENTS.md.
What it will never do
- Show server text on a 5xx. A Laravel app with
APP_DEBUG=trueanswers a crash with the SQL error and a stack trace. You get "Something went wrong on our side. If it keeps happening, quote reference 4f8c2a9e-…" instead, andfieldsis empty. - Read an unbounded body. It reads at most 64 KiB and cancels the rest.
- Give you HTML. The sentence is text: render it as text.
Result
interface HttpError {
status: number; // 0 = no response
code: string; // "body_too_large", "validation_failed", an app's own code ...
sentence: string; // one plain sentence, at most 300 code points
fields: Record<string, string>; // dotted path -> message; {} on a 5xx
retryAfter: number | null; // seconds
requestId: string | null; // for a support ticket
}
Options (every limit is a setting)
normalise(input, {
maxBodyBytes: 65536,
maxDepth: 64,
maxMessageLength: 300,
requestIdHeader: "x-request-id",
messages: { // the translation seam
not_found: "No encontrado.",
rate_limited: (c) => `Zu viele Anfragen. ${c.retryAfter ?? ""}`,
},
});
normalise({status, headers, body, now?}) takes a response you have already
read. formatBytes, formatDuration and sanitise are the shared sentence
helpers, and @particle-academy/fancy-http-errors/envelope.schema.json is the
envelope's JSON Schema.
Contract
The rules are fancy-conformance suites/http/SPEC.md, and this package runs
its http/error-envelope table in CI, as does the Laravel normaliser. Zero
runtime dependencies. MIT.

