ArctonArcton
API Reference

HTTP Errors

HttpError and the ready-to-throw Http status factories, from @arcton/core.

Overview

Throw a ready-made error instead of hand-rolling ctx.response.status = ...; return {...} at every place a request can fail:

import { Arcton, Http } 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.listen()

On its own this is still an uncaught error — turning it into a response is on you, the same way as any other throw. See Responding with errors for the try/catch pattern that maps HttpError's status/code/body onto ctx.response.

HttpError

Purpose — the error class every Http factory below returns; construct it directly for a status with no named factory.

Signature

class HttpError extends Error {
  constructor(status: number, code: string, message: string, body?: unknown)
  readonly status: number
  readonly code: string
  readonly body?: unknown
}

Parameters

ParameterTypeDescription
statusnumberThe HTTP status code, e.g. 451.
codestringA stable, machine-readable tag, e.g. 'UNAVAILABLE_FOR_LEGAL_REASONS'. Safe for a client to switch on, unlike message.
messagestringPassed to Error's own message.
bodyunknownOptional. The exact value a catch handler should send back instead of a default { code, message } shape.

Behavior — HttpError carries these fields but does nothing with them by itself; nothing in Arcton's pipeline catches an HttpError automatically (see Uncaught errors).

Example

import { HttpError } from '@arcton/core'

throw new HttpError(451, 'UNAVAILABLE_FOR_LEGAL_REASONS', 'Unavailable For Legal Reasons')

Http

Purpose — a namespace of ready-to-throw shortcuts, one per common status. Each one is a plain function — call it, don't new it — and returns an HttpError.

Signature

type StatusErrorFactory = (message?: string, body?: unknown) => HttpError

const Http: Record<string, StatusErrorFactory>

Parameters

ParameterTypeDescription
messagestringOptional. Defaults to the status's reason phrase (see the table below).
bodyunknownOptional. The exact value a catch handler should send back instead of a default { code, message } shape.

Return type — an HttpError.

Factories

FactoryStatuscodeDefault message
Http.BadRequest400'BAD_REQUEST'Bad Request
Http.Unauthorized401'UNAUTHORIZED'Unauthorized
Http.Forbidden403'FORBIDDEN'Forbidden
Http.NotFound404'NOT_FOUND'Not Found
Http.MethodNotAllowed405'METHOD_NOT_ALLOWED'Method Not Allowed
Http.Conflict409'CONFLICT'Conflict
Http.Gone410'GONE'Gone
Http.UnprocessableEntity422'UNPROCESSABLE_ENTITY'Unprocessable Entity
Http.TooManyRequests429'TOO_MANY_REQUESTS'Too Many Requests
Http.InternalServerError500'INTERNAL_SERVER_ERROR'Internal Server Error
Http.ServiceUnavailable503'SERVICE_UNAVAILABLE'Service Unavailable

throw Http.NotFound — the bare function reference, with no () — throws the function itself, not an HttpError. A catch block checking instanceof HttpError won't recognize it, and it reaches the adapter as an undifferentiated 500 instead. Always call the factory.

Example

import { Http } from '@arcton/core'

throw Http.Conflict('Email already registered', { field: 'email' })

ValidationError

Purpose — the error Arcton raises when a params, query or body schema fails (or a body can't be parsed). It reaches app.onError() like any other error.

Signature

class ValidationError extends HttpError {
  constructor(issues: ReadonlyArray<StandardSchemaV1.Issue>)
  readonly issues: ReadonlyArray<StandardSchemaV1.Issue>
}

Behavior — status is 400, code is 'VALIDATION_FAILED', and body is { issues }. issues is the exact array the schema library returned, unmodified. With no onError() (or one that returns nothing), it answers 400 with { "issues": [...] }. See Validation Errors.

Example

import { Arcton, ValidationError } from '@arcton/core'

const app = Arcton()

app.onError(err => {
  if (err instanceof ValidationError) return { issues: err.issues }
})

On this page