Error Handling

@workkit/errors provides a structured error hierarchy for Cloudflare Workers. Every error carries a machine-readable code, HTTP status, retry guidance, and optional context. No more guessing whether to retry or what status code to return.

Error Hierarchy

All errors extend WorkkitError:

Error Class	Code	Status	Retryable	Default Retry
`NotFoundError`	`WORKKIT_NOT_FOUND`	404	No	none
`ConflictError`	`WORKKIT_CONFLICT`	409	Yes	exponential (100ms base, 3 attempts)
`ValidationError`	`WORKKIT_VALIDATION`	400	No	none
`UnauthorizedError`	`WORKKIT_UNAUTHORIZED`	401	No	none
`ForbiddenError`	`WORKKIT_FORBIDDEN`	403	No	none
`TimeoutError`	`WORKKIT_TIMEOUT`	504	Yes	exponential
`RateLimitError`	`WORKKIT_RATE_LIMIT`	429	Yes	fixed
`ServiceUnavailableError`	`WORKKIT_SERVICE_UNAVAILABLE`	503	Yes	exponential
`BindingError`	`WORKKIT_BINDING_ERROR`	500	No	none
`BindingNotFoundError`	`WORKKIT_BINDING_NOT_FOUND`	500	No	none
`InternalError`	`WORKKIT_INTERNAL`	500	No	none
`ConfigError`	`WORKKIT_CONFIG`	500	No	none

D1-specific errors (from @workkit/d1):

Error Class	Code	Status	Retryable
`D1QueryError`	`WORKKIT_D1_QUERY`	500	No
`D1ConstraintError`	`WORKKIT_D1_CONSTRAINT`	409	No
`D1BatchError`	`WORKKIT_D1_BATCH`	500	No
`D1MigrationError`	`WORKKIT_D1_MIGRATION`	500	No

Creating Errors

import {
  NotFoundError,
  ConflictError,
  ValidationError,
  UnauthorizedError,
  TimeoutError,
  InternalError,
} from '@workkit/errors'

// Simple
throw new NotFoundError('User', '42')
// message: 'User "42" not found'

// With context
throw new NotFoundError('User', '42', {
  context: { table: 'users', query: 'SELECT ...' },
})

// Validation with issues
throw new ValidationError('Invalid input', [
  { path: ['email'], message: 'Must be a valid email' },
  { path: ['age'], message: 'Must be at least 18' },
])

// With cause (error chaining)
try {
  await someOperation()
} catch (cause) {
  throw new InternalError('Operation failed', { cause })
}

// With custom retry strategy
throw new TimeoutError('API call', 5000, {
  retryStrategy: { kind: 'fixed', delayMs: 2000, maxAttempts: 5 },
})

HTTP Response Mapping

Convert any WorkkitError to an HTTP response:

import { errorToResponse } from '@workkit/errors'

try {
  // ... handler logic
} catch (error) {
  if (error instanceof WorkkitError) {
    return errorToResponse(error)
    // Response { status: 404, body: { error: { code, message, statusCode } } }
  }
  return new Response('Internal Server Error', { status: 500 })
}

The response body includes the error code and message but strips internal details (stack trace, cause) for security:

{
  "error": {
    "code": "WORKKIT_NOT_FOUND",
    "message": "User \"42\" not found",
    "statusCode": 404
  }
}

For ValidationError, issues are included:

{
  "error": {
    "code": "WORKKIT_VALIDATION",
    "message": "Invalid input",
    "statusCode": 400,
    "issues": [
      { "path": ["email"], "message": "Must be a valid email" }
    ]
  }
}

For RateLimitError, a Retry-After header is set automatically.

Creating Errors from HTTP Status Codes

Wrap upstream API responses:

import { fromHttpStatus } from '@workkit/errors'

const response = await fetch('https://api.example.com/data')
if (!response.ok) {
  throw fromHttpStatus(response.status, await response.text())
  // 404 -> NotFoundError
  // 401 -> UnauthorizedError
  // 429 -> RateLimitError
  // 503 -> ServiceUnavailableError
  // 5xx -> InternalError
}

Retry Logic

Every error carries retry guidance. Use the built-in helpers to implement retry loops:

Retry Strategies

import { RetryStrategies } from '@workkit/errors'

RetryStrategies.none()                    // { kind: 'none' }
RetryStrategies.immediate(3)              // { kind: 'immediate', maxAttempts: 3 }
RetryStrategies.fixed(1000, 3)            // { kind: 'fixed', delayMs: 1000, maxAttempts: 3 }
RetryStrategies.exponential(500, 30000, 5) // { kind: 'exponential', baseMs: 500, maxMs: 30000, maxAttempts: 5 }

Calculating Delay

import { getRetryDelay } from '@workkit/errors'

const strategy = { kind: 'exponential', baseMs: 500, maxMs: 30000, maxAttempts: 5 }

getRetryDelay(strategy, 1)  // ~500ms (with jitter)
getRetryDelay(strategy, 2)  // ~1000ms
getRetryDelay(strategy, 3)  // ~2000ms
getRetryDelay(strategy, 5)  // ~8000ms
getRetryDelay(strategy, 6)  // null (exceeded maxAttempts)

Exponential backoff includes +/-25% jitter to prevent thundering herd.

Retry Helper

import { isRetryable, getRetryDelay, getRetryStrategy } from '@workkit/errors'

async function withRetry<T>(fn: () => Promise<T>, maxAttempts = 5): Promise<T> {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn()
    } catch (error) {
      if (!isRetryable(error) || attempt === maxAttempts) {
        throw error
      }

      const strategy = getRetryStrategy(error)
      const delay = getRetryDelay(strategy, attempt)
      if (delay === null) throw error

      await new Promise(resolve => setTimeout(resolve, delay))
    }
  }
  throw new Error('unreachable')
}

// Usage
const data = await withRetry(() => db.first('SELECT ...'))

Type Guards

import { isWorkkitError, isErrorCode } from '@workkit/errors'

try {
  await someOperation()
} catch (error) {
  if (isWorkkitError(error)) {
    // error is WorkkitError -- has code, statusCode, retryable, etc.
    console.log(error.code)
  }

  if (isErrorCode(error, 'WORKKIT_NOT_FOUND')) {
    // Handle not found specifically
  }
}

Serialization

Serialize errors for logging pipelines:

import { serializeError, wrapError } from '@workkit/errors'

// Serialize any error (WorkkitError or native) to a structured format
const serialized = serializeError(error)
// {
//   name: 'NotFoundError',
//   code: 'WORKKIT_NOT_FOUND',
//   message: 'User "42" not found',
//   statusCode: 404,
//   retryable: false,
//   retryStrategy: { kind: 'none' },
//   timestamp: '2024-01-01T00:00:00.000Z',
//   context: { resource: 'User', identifier: '42' }
// }

// Wrap an unknown error as a WorkkitError
const wrapped = wrapError(new TypeError('oops'))
// InternalError with the original as cause

The toJSON() method on WorkkitError produces the same serialized format. Error chains (cause) are serialized recursively.

Error Context

Every error can carry structured context for debugging:

const error = new NotFoundError('User', '42', {
  context: {
    table: 'users',
    query: 'SELECT * FROM users WHERE id = ?',
    params: [42],
  },
})

console.log(error.context)
// { resource: 'User', identifier: '42', table: 'users', query: '...', params: [42] }

// Context appears in toString() and toJSON()
console.log(error.toString())
// [WORKKIT_NOT_FOUND] NotFoundError: User "42" not found | context: {...}

Pattern: Global Error Handler

import { isWorkkitError, errorToResponse, wrapError, serializeError } from '@workkit/errors'

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    try {
      return await handleRequest(request, env)
    } catch (error) {
      const workitError = isWorkkitError(error) ? error : wrapError(error)

      // Log structured error
      console.error(JSON.stringify(serializeError(workitError)))

      // Return appropriate HTTP response
      return errorToResponse(workitError)
    }
  },
}

Domain-specific error codes

@workkit/errors is the base. Higher-level packages add their own codes that extend the same hierarchy:

Package	Codes
`@workkit/agent`	`WORKKIT_AGENT_HANDOFF_CYCLE`, `WORKKIT_AGENT_BUDGET`
`@workkit/memory`	`STORAGE_ERROR`, `EMBEDDING_ERROR`, `VECTORIZE_ERROR`, `CACHE_ERROR`, `ENCRYPTION_ERROR`, `COMPACTION_ERROR`, `NOT_FOUND`, `IDEMPOTENCY_ERROR` (returned via the `MemoryResult<T>` discriminated union, not thrown)
`@workkit/workflow`	`WorkflowError` carries `executionId`, `failedStep`, `stepAttempt`, plus the full journal
`@workkit/turnstile`	`WORKKIT_TURNSTILE`

Use serializeError(err) for log emission and errorToResponse(err) for HTTP responses regardless of which package raised the error.