Error Handling

Typed Fetch provides specific error classes as individual exports for optimal tree-shaking.

Available Error Classes

The library provides comprehensive coverage of HTTP error status codes. For detailed information about each status code, see the MDN HTTP Status Reference.

• 4xx Client Errors:

  • BadRequest (400)
  • PaymentRequired (402)
  • Unauthorized (401)
  • Forbidden (403)
  • NotFound (404)
  • MethodNotAllowed (405)
  • NotAcceptable (406)
  • ProxyAuthenticationRequired (407)
  • RequestTimeout (408)
  • Conflict (409)
  • Gone (410)
  • LengthRequired (411)
  • PreconditionFailed (412)
  • RequestTooLong (413)
  • RequestUriTooLong (414)
  • UnsupportedMediaType (415)
  • RequestedRangeNotSatisfiable (416)
  • ExpectationFailed (417)
  • ImATeapot (418)
  • MisdirectedRequest (421)
  • UnprocessableEntity (422)
  • Locked (423)
  • FailedDependency (424)
  • UpgradeRequired (426)
  • PreconditionRequired (428)
  • TooManyRequests (429)
  • RequestHeaderFieldsTooLarge (431)
  • UnavailableForLegalReasons (451)

• 5xx Server Errors:

  • InternalServer (500)
  • NotImplemented (501)
  • BadGateway (502)
  • ServiceUnavailable (503)
  • GatewayTimeout (504)
  • HttpVersionNotSupported (505)
  • InsufficientStorage (507)
  • NetworkAuthenticationRequired (511)

• Network Errors:

  • Network

Example

import { typedFetch, NotFoundError, UnauthorizedError, NetworkError } from '@pbpeterson/typed-fetch';

// Specify expected client errors for this endpoint
type ExpectedErrors = NotFoundError | UnauthorizedError;
const { response, error } = await typedFetch<User, ExpectedErrors>('/api/users/123');

if (error) {
  if (error instanceof NotFoundError) {
    console.log('User not found');
    // Access error response body
    const details = await error.json();
    console.log('Error details:', details);
  } else if (error instanceof UnauthorizedError) {
    console.log('Please log in');
    // Access error response body with clone for multiple reads
    const message = await error.clone().text();
    console.log('Auth error message:', message);
  } else if (error instanceof NetworkError) {
    console.log('Network error:', error.message);
  } else {
    // Server errors (5xx) - always included
    console.log('Server error:', error.statusText);
    
    // Access response data in different formats
    try {
      const errorData = await error.json();
      console.log('Server error details:', errorData);
    } catch {
      const errorText = await error.clone().text();
      console.log('Server error text:', errorText);
    }
  }
}

Specific Client Error Types

You can specify expected client errors using generics.

import { NotFoundError } from '@pbpeterson/typed-fetch';

type ExpectedErrors = NotFoundError;
const result = await typedFetch<User, ExpectedErrors>('/api/users/123');
const { response, error } = result;

if (error) {
  // Here, response is null,
  // and error is NotFoundError | ServerErrors | NetworkError
  console.log('Error occurred:', error.statusText);
} else {
  // Here, error is null, and response is TypedResponse<User>
  // TypeScript knows response is not null
  const user = await response.json(); // Type: User
}