Error Handling Patterns
Problem
A failed request needs user-facing treatment without treating cancellation as a server failure.
Solution
Narrow Courier's typed error classes before escalating unknown failures.
ts
import {
CourierAbortError,
CourierHttpError,
CourierNetworkError,
CourierParseError,
CourierTimeoutError,
createCourier,
} from '@vielzeug/courier';
const courier = createCourier({ baseUrl: 'https://api.example.com' });
async function loadUser(): Promise<string> {
try {
return (await courier.get<{ name: string }>('/users/1', { timeout: 2_000 })).name;
} catch (error) {
if (error instanceof CourierAbortError) return 'Cancelled';
if (error instanceof CourierTimeoutError) return 'Timed out; retry.';
if (CourierHttpError.is(error, 404)) return 'User not found.';
if (error instanceof CourierNetworkError) return 'Check your connection.';
if (error instanceof CourierParseError) return 'The server returned an unreadable response.';
throw error;
}
}Problem details
Read problem when the server answers with an RFC 9457 document, and keep the HTTP status as the routing key.
ts
import { CourierHttpError, createCourier } from '@vielzeug/courier';
const courier = createCourier({ baseUrl: 'https://api.example.com' });
async function submit(body: unknown): Promise<string> {
try {
await courier.post('/invoices', { body });
return 'Saved';
} catch (error) {
if (!CourierHttpError.is(error, 422)) throw error;
const fieldErrors = error.problem?.['errors'] as Record<string, string> | undefined;
return fieldErrors ? Object.values(fieldErrors).join(', ') : (error.problem?.detail ?? 'The request was rejected.');
}
}Pitfalls
- A
CourierHttpErrorhas a response; aCourierNetworkErrordoes not. - Do not display cancellation as an application error during navigation.
CourierSchemaValidationErrorcarries the raw pre-validationdata.problemisundefinedunless the response has an object body andapplication/problem+json; branch on HTTPstatusfirst.- Courier does not validate extension-member shapes; narrow them before using them as application data.