Error Handling

SpaceNode has a comprehensive error system. All errors are automatically caught and returned as JSON.

HttpError

import { HttpError } from 'SpaceNode'

// Direct throw
throw new HttpError(404, 'User not found')

// With details
throw new HttpError(400, 'Validation failed', [
  { field: 'email', message: 'Invalid email' }
])

Response Format

{
  "error": "User not found",
  "status": 404
}

// With details:
{
  "error": "Validation failed",
  "status": 400,
  "details": [{ "field": "email", "message": "Invalid" }]
}

ValidationError

import { ValidationError } from 'SpaceNode'

throw new ValidationError([
  { field: 'email', message: 'email is required' },
  { field: 'password', message: 'min 6 chars' },
])

ModuleError

Thrown during startup when a module’s configuration is invalid (missing routes, bad exports, etc.). Not an HTTP error — this crashes the app on boot so you catch it early.

import { ModuleError } from 'SpaceNode'

// Thrown automatically by the framework:
// ModuleError: [Module: auth] Missing routes

// Properties:
// err.moduleName  → 'auth'
// err.message     → '[Module: auth] Missing routes'
// err.name        → 'ModuleError'

Global Error Handler

const app = await createApp()

app.onError((err, request) => {
  console.error(`[${request.method}] ${request.path}:`, err.message)
  // Send to Sentry, Datadog, etc.
})

Auto-Handled Errors

Scenario	Status	Error
Route not found	404	`404.html` (if exists) or JSON `Not found`
Wrong HTTP method	405	`Method not allowed`
No auth token	401	`Authorization required`
Invalid token	401	`Invalid or expired token`
Wrong role	403	`Access denied`
Rate limit exceeded	429	`Too many requests`
Invalid JSON body	400	`Invalid JSON`
Body too large	413	`Request body too large`
Multipart parse error	400	`Multipart parse error`
Unhandled exception	500	`Internal Server Error`