Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/unjs/ofetch/llms.txt

Use this file to discover all available pages before exploring further.

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us