ArctonArcton
Errores

Global Error Handler

Captura cualquier error no manejado en un solo lugar con app.onError()

Los errores no capturados llegan al adapter del runtime como un 500 genérico, a menos que algo los capture antes. app.onError() registra un único handler que captura cualquiera de esos errores — de un provider, un middleware, un parser de body o el propio handler de la ruta — antes de que lleguen tan lejos:

import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/risky', () => {
  throw new Error('boom')
})

app.onError((err, ctx) => {
  console.error(err)
  return { error: 'Something went wrong' }
})

app.listen()

Un request a /risky ahora responde con lo que devuelve el handler en lugar del texto genérico del 500 del adapter. onError() es opt-in — una app que nunca lo llama sigue comportándose exactamente como describen los errores no capturados.

El status por defecto es 500

Si el handler no asigna ctx.response.status por su cuenta, la respuesta usa 500 por defecto. Asígnalo explícitamente para responder con otra cosa — por ejemplo, distinguiendo HttpError para reutilizar el status que ya trae:

import { Arcton, Http, HttpError } from '@arcton/core'

declare function findOrder(id: string): { id: string } | undefined

const app = Arcton()

app.get('/orders/:id', ctx => {
  const order = findOrder(ctx.params.id)
  if (!order) throw Http.NotFound(`Order ${ctx.params.id} not found`)
  return order
})

app.onError((err, ctx) => {
  if (err instanceof HttpError) {
    ctx.response.status = err.status
    return err.body ?? { code: err.code, message: err.message }
  }
  return { code: 'INTERNAL_SERVER_ERROR', message: 'Internal Server Error' }
})

app.listen()

Un status ya asignado antes del throw — por ejemplo, por un middleware que corrió antes — se conserva si el handler nunca toca ctx.response.status; el valor por defecto de 500 solo se aplica cuando nada asignó un status en absoluto.

Como cualquier handler, onError() puede devolver un valor plano (mapeado con las mismas reglas de Response) o un objeto Response directamente, que se envía sin cambios.

Los errores de validación también pasan por acá

Un esquema de params, query o body que falla — o un body que Arcton no puede interpretar en absoluto — llega a onError() como un ValidationError: una subclase de HttpError cuyos issues son exactamente los que devolvió la librería de esquemas. Un Content-Type de body no soportado llega como un HttpError con status 415.

import { Arcton, ValidationError } from '@arcton/core'
import * as v from 'valibot'

const app = Arcton()

app.post('/users', {
  body: v.object({ email: v.pipe(v.string(), v.email()) }),
  handler: ctx => ({ created: ctx.body })
})

app.onError((err, ctx) => {
  if (err instanceof ValidationError) {
    return { error: 'Invalid request', issues: err.issues }
  }
  return { error: 'Something went wrong' }
})

app.listen()

La respuesta de arriba es un 400 aunque el handler nunca asignó un status: para estos dos errores de request el status por defecto es el suyo propio (400, 415) en lugar de 500.

Los errores de validación se responden justo donde ocurren, así que el middleware que envuelve la ruta — CORS, logging de requests — sigue viendo una respuesta normal después de await next(). Cualquier otro error lanzado atraviesa primero ese middleware.

Devolver nada declina el error

onError() maneja un error devolviendo un valor o una Response. Si no devuelve nada, se aplica en su lugar el comportamiento por defecto de Arcton: un error de validación responde 400 con el body de issues, un Content-Type no soportado responde un 415 vacío, y cualquier otro error se propaga al adapter exactamente como con ningún handler registrado. Eso hace de onError() un buen lugar para loguear todo y quedarte solo con las respuestas que te interesan.

También corre para el fallback de 404/405

El middleware global corre incluso cuando nada matchea el request, así que onError() también cubre un throw ahí:

import { Arcton } from '@arcton/core'

declare function logRequest(request: Request): void

const app = Arcton()

app.use(async (ctx, next) => {
  logRequest(ctx.request) // lanza un error si el logger está caído
  await next()
})

app.onError((err, ctx) => ({ error: 'Something went wrong' }))

app.listen()

Es un único handler, a nivel de la app completa

Solo existe un handler de onError() por app — registrar uno nuevo reemplaza al anterior — y solo se consulta el de la instancia cuyo propio listen() termina sirviendo el request. Si construyes parte de tu app como un módulo separado y lo montas con app.use(módulo), un onError() registrado en ese módulo no tiene ningún efecto; los módulos componen rutas, middleware y providers dentro de la app que los monta, no un límite de errores independiente.

Para un límite acotado a una sola sección de la app, envuelve next() en un try/catch dentro de un middleware con scope — ver Capturar un error lanzado dentro de un middleware. Los dos se combinan bien: un try/catch con scope maneja lo que reconoce y relanza el resto, que entonces llega a onError() como el catch-all final.

Si el propio handler de onError() lanza un error, ese error no vuelve a pasarle por su cuenta — se propaga de la misma forma en que lo haría un error no capturado sin ningún handler registrado.

En esta página