jsschools

createError() (server)

Creates an HTTP error to throw from a server route, setting the status code.

Since Nuxt 3.0 Spec ↗

Syntax

throw createError({ statusCode, statusMessage, data })

Parameters

NameTypeRequiredDescription
input { statusCode, statusMessage, message, data, fatal } | string Yes Error details; `statusCode` becomes the HTTP response status.

Returns

H3Error — An error object suitable for throwing in handlers.

Examples

// server/api/users/[id].get.ts
export default defineEventHandler(async (event) => {
  const user = await db.users.find(getRouterParam(event, 'id'))
  if (!user) {
    throw createError({
      statusCode: 404,
      statusMessage: 'User not found',
    })
  }
  return user
})

export default defineEventHandler((event) => {
  if (!isAuthed(event)) {
    throw createError({
      statusCode: 403,
      statusMessage: 'Forbidden',
      data: { reason: 'insufficient_role' },
    })
  }
})

Notes

In server handlers, the thrown `statusCode` sets the HTTP response status and `statusMessage` the status text; `data` is included in the JSON error body. Avoid leaking internals in `statusMessage`. The same `createError` is used client-side but with `fatal` semantics for pages.

See also