Skip to main content

Typed errors

Three endpoints that fail in three different ways: an unknown product, a wrong password and a sold-out reservation. Each panel shows its error type and narrows it to the right message. Break the network makes every request time out, which shows the error that all of them share.

intermediateerrorstypescriptuseFetchuseSubmit
import { TimeoutError } from "@hyper-fetch/core";
import { useFetch, useSubmit } from "@hyper-fetch/react";
import { type ReactNode, useState } from "react";

import { getProduct, login, reserve } from "./api";

/** The global error branch, the same for every request: HyperFetch's own `Error` objects. */
const TransportError = ({ error }: { error: Error }) => (
<p className="error">
{error instanceof TimeoutError ? "The server took too long." : "No connection to the server."}{" "}
<small>({error.name})</small>
</p>
);

const Panel = ({ title, type, children }: { title: string; type: string; children: ReactNode }) => (
<article>
<header>
<strong>{title}</strong>
<br />
<code>error: {type}</code>
</header>
{children}
</article>
);

const Product = ({ broken }: { broken: boolean }) => {
const [productId, setProductId] = useState(1);
const request = getProduct.setParams({ productId });
const { data, error, loading } = useFetch(broken ? request.setOptions({ timeout: 1 }) : request, {
dependencies: [broken],
});

return (
<Panel title="Product" type="NotFoundError | Error">
<div role="group">
<button type="button" className="outline" onClick={() => setProductId(1)}>
#1
</button>
<button type="button" className="outline" onClick={() => setProductId(9999)}>
#9999
</button>
</div>
{loading && <p aria-busy="true">Loading...</p>}
{/* `instanceof Error` splits the global error from the endpoint error. Each branch is fully typed. */}
{!loading && error instanceof Error && <TransportError error={error} />}
{!loading && error && !(error instanceof Error) && <p className="error">Not found: {error.message}</p>}
{!loading && !error && data && (
<p>
{data.title} <ins>${data.price}</ins>
</p>
)}
</Panel>
);
};

const Login = ({ broken }: { broken: boolean }) => {
const { submit, submitting, data, error } = useSubmit(broken ? login.setOptions({ timeout: 1 }) : login);

return (
<Panel title="Login" type="InvalidCredentialsError | Error">
<div role="group">
<button
type="button"
className="outline"
onClick={() => submit({ payload: { username: "emilys", password: "wrong" } })}
>
Wrong password
</button>
<button
type="button"
className="outline"
onClick={() => submit({ payload: { username: "emilys", password: "emilyspass" } })}
>
Right password
</button>
</div>
{submitting && <p aria-busy="true">Signing in...</p>}
{!submitting && error instanceof Error && <TransportError error={error} />}
{!submitting && error && !(error instanceof Error) && <p className="error">Check your username and password.</p>}
{!submitting && !error && data && <p>Welcome, {data.firstName}.</p>}
</Panel>
);
};

const Reservation = ({ broken }: { broken: boolean }) => {
const { submit, submitting, data, error } = useSubmit(broken ? reserve.setOptions({ timeout: 1 }) : reserve);

return (
<Panel title="Reservation" type="ProblemDetails | Error">
<div role="group">
<button
type="button"
className="outline"
onClick={() => submit({ params: { status: 409, message: "No items left" } })}
>
Sold out
</button>
<button
type="button"
className="outline"
onClick={() => submit({ params: { status: 200, message: "Reserved" } })}
>
In stock
</button>
</div>
{submitting && <p aria-busy="true">Reserving...</p>}
{!submitting && error instanceof Error && <TransportError error={error} />}
{/* Problem details carry their own status and title, so the branch can go one level deeper. */}
{!submitting && error && !(error instanceof Error) && (
<p className="error">
{error.status === 409 ? "Sold out" : error.title}: {error.detail}
</p>
)}
{!submitting && !error && data && <p>{data.message}</p>}
</Panel>
);
};

export const App = () => {
const [broken, setBroken] = useState(false);

return (
<main className="container">
<hgroup>
<h1>Typed errors</h1>
<p>
Every endpoint fails in its own way. The error type says how, and the UI narrows it before showing a message.
</p>
</hgroup>
<label>
<input type="checkbox" role="switch" checked={broken} onChange={(event) => setBroken(event.target.checked)} />
Break the network (1 ms timeout)
</label>
<div className="grid-3">
<Product broken={broken} />
<Login broken={broken} />
<Reservation broken={broken} />
</div>
</main>
);
};
Run locallynpx tiged BetterTyped/hyper-fetch/examples/react/typed-errors hyper-fetch-react-typed-errors && cd hyper-fetch-react-typed-errors && npm install && npm run dev
What it shows
  1. A global error type on the client: createClient<{ error: Error }>() for failures of the transport.
  2. An endpoint error type with the error generic. The hooks return the union of both.
  3. instanceof Error splits HyperFetch's own errors from the JSON error bodies of the server.
  4. Deeper narrowing on fields of the endpoint error, such as status in problem details.

How it works​

  1. api.ts sets the global error to Error. HyperFetch reports network failures, timeouts and aborts as Error objects such as TimeoutError, so that is what every request can fail with.

  2. Each request adds the body its endpoint sends on failure. getProduct has NotFoundError, login has InvalidCredentialsError, and reserve has ProblemDetails:

    export const reserve = client.createRequest<{
    response: { status: number; message: string };
    error: ProblemDetails;
    }>()({ endpoint: "/http/:status/:message", method: "POST" });
  3. useFetch(getProduct...) and useSubmit(login) return error typed as the endpoint error or Error. Without a check, only fields shared by both members are available.

  4. error instanceof Error picks the global branch, rendered by one shared TransportError component. In the other branch TypeScript knows the exact endpoint type, so error.message, or error.status and error.detail for problem details, are typed.

  5. Break the network sets setOptions({ timeout: 1 }) on all three requests. They resolve with a TimeoutError, which TransportError names with a second instanceof check.

The error handling example shows the same generics for one endpoint, with a retry button and an error log.

When to use it
  • APIs whose endpoints return different error bodies, such as auth, validation and problem details.
  • Shared error components for network failures, with messages per endpoint for the rest.
  • Code reviews: a new error shape changes the type, and every place that shows it fails to compile.

Summary

The client's error generic covers what every request can fail with, and each request's error generic adds what its endpoint sends. Narrowing the union with instanceof and its fields gives each case its own typed message.