Your privacy choices

We use necessary cookies, and others only if you allow them. You can change your mind at any time.

FH

@particle-academy/fancy-http-errors

@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.

Backend · renders no UITS
Backend · renders no UI
Nothing to preview — install it and call the typed API, or hand it to an agent.
$npm install @particle-academy/fancy-http-errors

API surface

Headless package — drive it from code or an agent. No component grid.

This package renders no UI surface. It exposes a typed code API; issues are tracked on GitHub.
readmeREADME.mdView on GitHub →

@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 id fancy-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=true answers 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, and fields is 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.

What next
Install it, then call the API from your code or over MCP.