Error Handling

Automatic error throwing for failed requests with detailed error information and error data access

ofetch automatically throws errors for failed HTTP requests (status codes 400-599), making error handling straightforward and consistent.

Automatic Error Throwing

Unlike native fetch, ofetch automatically throws errors when the response status is 4xx or 5xx:

import { ofetch } from 'ofetch'

try {
  const data = await ofetch('/api/user/999')
} catch (error) {
  console.error(error)
  // FetchError: [GET] "/api/user/999": 404 Not Found
}

This eliminates the need to manually check response.ok after every request.

FetchError Type

When a request fails, ofetch throws a FetchError with detailed information:

import { ofetch, FetchError } from 'ofetch'

try {
  await ofetch('/api/protected', {
    method: 'POST',
    body: { name: 'test' }
  })
} catch (error) {
  if (error instanceof FetchError) {
    console.log(error.message)      // [POST] "/api/protected": 403 Forbidden
    console.log(error.status)       // 403
    console.log(error.statusCode)   // 403 (alias)
    console.log(error.statusText)   // "Forbidden"
    console.log(error.statusMessage)// "Forbidden" (alias)
    console.log(error.request)      // Request object or URL string
    console.log(error.response)     // Response object
    console.log(error.data)         // Parsed response body
    console.log(error.options)      // Request options used
  }
}

FetchError Properties

message · string

Formatted error message in the format: [METHOD] "url": status statusText errorMessage

Example: [GET] "/api/user": 404 Not Found

status · number | undefined

HTTP status code of the response (e.g., 404, 500)

statusCode · number | undefined

Alias for status

statusText · string | undefined

HTTP status text (e.g., “Not Found”, “Internal Server Error”)

statusMessage · string | undefined

Alias for statusText

data · any

The parsed response body, same as response._data. This is particularly useful for API errors that return error details in the response body.

request · FetchRequest

The request URL string or Request object that was used

response · FetchResponse | undefined

The Response object with the parsed data available as _data property

options · FetchOptions

The resolved request options that were used

Accessing Error Data

The error.data property contains the parsed response body, which is useful for API errors:

import { ofetch } from 'ofetch'

try {
  await ofetch('/api/users', {
    method: 'POST',
    body: { email: 'invalid-email' }
  })
} catch (error) {
  // Access structured error information from the API
  console.log(error.data)
  // {
  //   status: 400,
  //   message: "Validation failed",
  //   errors: {
  //     email: "Invalid email format"
  //   }
  // }
  
  // Display user-friendly error message
  if (error.data?.errors) {
    for (const [field, message] of Object.entries(error.data.errors)) {
      console.error(`${field}: ${message}`)
    }
  }
}

The error.data property is the same as error.response._data, providing convenient access to the parsed response body.

Ignoring Response Errors

You can disable automatic error throwing using the ignoreResponseError option:

ignoreResponseError · boolean · default: "false"

When set to true, ofetch will not throw errors for 4xx and 5xx responses. Instead, it returns the response normally.

import { ofetch } from 'ofetch'

// Returns response object instead of throwing
const response = await ofetch('/api/resource', {
  ignoreResponseError: true
})

if (response.status === 404) {
  console.log('Resource not found')
} else if (response.status >= 500) {
  console.log('Server error')
}

This is useful when you need to handle different status codes explicitly:

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

switch (response.status) {
  case 200:
    console.log('Success:', response._data)
    break
  case 404:
    console.log('Not found')
    break
  case 403:
    console.log('Forbidden')
    break
  default:
    console.log('Other status:', response.status)
}

Error Status Codes

ofetch throws errors for all status codes between 400 and 599 (inclusive):

• 4xx Client Errors: 400-499 (Bad Request, Unauthorized, Forbidden, Not Found, etc.)
• 5xx Server Errors: 500-599 (Internal Server Error, Bad Gateway, Service Unavailable, etc.)

Error Cause

When the underlying fetch operation fails (network error, timeout, etc.), the original error is preserved in the cause property:

try {
  await ofetch('https://invalid-domain.example.com')
} catch (error) {
  console.log(error.cause) // Original network error
}

ofetch polyfills the cause property for runtimes that don’t support it natively.

TypeScript Error Handling

You can type the error data for better TypeScript support:

import { ofetch, FetchError } from 'ofetch'

interface ApiError {
  message: string
  code: string
  errors?: Record<string, string>
}

try {
  await ofetch('/api/users', { method: 'POST', body: {} })
} catch (error) {
  if (error instanceof FetchError<ApiError>) {
    // error.data is now typed as ApiError
    console.log(error.data?.message)
    console.log(error.data?.code)
  }
}