FetchError

Error types and error handling in ofetch

Overview

ofetch throws FetchError instances when requests fail. These errors provide detailed information about what went wrong, including the request, response, and status information.

FetchError Class

The main error class thrown by ofetch.

export class FetchError<T = any> extends Error implements IFetchError<T> {
  constructor(message: string, opts?: { cause: unknown })
}

export interface FetchError<T = any> extends IFetchError<T> {}

Constructor Parameters:

message · string · required

Error message describing what went wrong

opts.cause · unknown

The underlying error that caused this error (error chaining)

Properties:

Inherits all properties from IFetchError interface (see below).

Example:

try {
  await ofetch('/api/users/999')
} catch (error) {
  if (error instanceof FetchError) {
    console.error('Status:', error.status)
    console.error('Message:', error.message)
    console.error('Data:', error.data)
  }
}

IFetchError Interface

Interface defining the structure of fetch errors.

export interface IFetchError<T = any> extends Error {
  request?: FetchRequest;
  options?: FetchOptions;
  response?: FetchResponse<T>;
  data?: T;
  status?: number;
  statusText?: string;
  statusCode?: number;
  statusMessage?: string;
}

Properties

name · string

Always "FetchError"

message · string

Error message in format: [METHOD] "url": status statusText errorMessage

cause · unknown

The underlying error that caused this error, if available

request · FetchRequest | undefined

The original request URL or Request object

options · FetchOptions | undefined

The fetch options used for the request. See FetchOptions.

response · FetchResponse<T> | undefined

The response object if available. See FetchResponse.

data · T | undefined

Parsed response data from response._data

status · number | undefined

HTTP status code from the response

statusText · string | undefined

HTTP status text from the response

statusCode · number | undefined

Alias for status

statusMessage · string | undefined

Alias for statusText

Error Message Format

FetchError messages follow this format:

[METHOD] "url": status statusText errorMessage

Examples:

[GET] "https://api.example.com/users/999": 404 Not Found
[POST] "https://api.example.com/users": 400 Bad Request Validation failed
[GET] "https://api.example.com/data": <no response> Network error

Error Handling

Basic Error Handling

try {
  const user = await ofetch('/api/users/123')
} catch (error) {
  if (error instanceof FetchError) {
    console.error(`HTTP ${error.status}: ${error.statusText}`)
    console.error('Response data:', error.data)
  }
}

Handling Specific Status Codes

try {
  const user = await ofetch('/api/users/123')
} catch (error) {
  if (error instanceof FetchError) {
    switch (error.status) {
      case 404:
        console.error('User not found')
        break
      case 401:
        console.error('Unauthorized')
        redirectToLogin()
        break
      case 500:
        console.error('Server error')
        break
      default:
        console.error('Request failed:', error.message)
    }
  }
}

Suppressing Errors

Use ignoreResponseError to prevent errors from being thrown:

const response = await ofetch('/api/users/123', {
  ignoreResponseError: true
})

if (response === null) {
  // Handle 404 or other errors
}

Using Hooks for Error Handling

Handle errors globally using hooks:

const apiFetch = ofetch.create({
  onResponseError({ response, error }) {
    if (response.status === 401) {
      redirectToLogin()
    }
    
    // Log to error tracking
    errorTracker.log({
      status: response.status,
      url: response.url,
      data: response._data
    })
  },
  onRequestError({ error }) {
    // Network errors, timeouts, etc.
    console.error('Request failed:', error)
  }
})

Network Errors vs HTTP Errors

Network Errors (triggered in onRequestError):

• Network connectivity issues
• Timeouts
• Aborted requests
• CORS errors

HTTP Errors (triggered in onResponseError):

• 4xx client errors (400, 401, 404, etc.)
• 5xx server errors (500, 502, 503, etc.)

await ofetch('/api/data', {
  onRequestError({ error }) {
    // Network errors
    console.error('Network error:', error.message)
  },
  onResponseError({ response }) {
    // HTTP errors
    console.error('HTTP error:', response.status)
  }
})

createFetchError

Internal function used to create FetchError instances from a FetchContext.

export function createFetchError<T = any>(
  ctx: FetchContext<T>
): IFetchError<T>

This function is used internally by ofetch and typically not needed in application code.

Type Parameters

T · any · default: "any"

The type of the response data and error data

Related

• FetchOptions - Request options including ignoreResponseError
• FetchHooks - onRequestError and onResponseError hooks
• FetchContext - Context passed to error hooks
• FetchResponse - Response interface