fix: return proper HTTP status codes and stop coercing input (#129)

#125: HTTP API now returns correct status codes:
- 400 for validation errors (bad input, malformed JSON)
- 404 for not found (run, job)
- 409 for conflict (retrigger pending/leased, cancel completed, delete active)
- 500 only for unexpected internal errors

Added typed error classes: DurablyError, NotFoundError, ValidationError,
ConflictError — all exported for user-land error handling.

#127: Remove all input coercion in POST /trigger. body.input is passed
directly to job.trigger() — Zod handles validation and returns 400 for
invalid/missing input. No more silent null→{} or undefined→{} conversion.

Closes #125
Closes #127

Co-authored-by: Claude Opus 4.6 <[email protected]>

Author: coji

packages/durably/src/durably.ts

@@ -4,7 +4,13 @@ import { monotonicFactory } from 'ulidx'
 import type { z } from 'zod'
 import { createStepContext } from './context'
 import type { JobDefinition } from './define-job'
-import { CancelledError, getErrorMessage, LeaseLostError } from './errors'
+import {
+  CancelledError,
+  ConflictError,
+  getErrorMessage,
+  LeaseLostError,
+  NotFoundError,
+} from './errors'
 import {
   type AnyEventInput,
   type DurablyEvent,
@@ -435,7 +441,7 @@ function createDurablyInstance<
   async function getRunOrThrow(runId: string): Promise<Run<TLabels>> {
     const run = await storage.getRun(runId)
     if (!run) {
-      throw new Error(`Run not found: ${runId}`)
+      throw new NotFoundError(`Run not found: ${runId}`)
     }
     return run as Run<TLabels>
   }
@@ -808,14 +814,14 @@ function createDurablyInstance<
     async retrigger(runId: string): Promise<Run<TLabels>> {
       const run = await getRunOrThrow(runId)
       if (run.status === 'pending') {
-        throw new Error(`Cannot retrigger pending run: ${runId}`)
+        throw new ConflictError(`Cannot retrigger pending run: ${runId}`)
       }
       if (run.status === 'leased') {
-        throw new Error(`Cannot retrigger leased run: ${runId}`)
+        throw new ConflictError(`Cannot retrigger leased run: ${runId}`)
       }
       const job = jobRegistry.get(run.jobName)
       if (!job) {
-        throw new Error(`Unknown job: ${run.jobName}`)
+        throw new NotFoundError(`Unknown job: ${run.jobName}`)
       }
 
       // Validate original input against current schema
@@ -846,21 +852,21 @@ function createDurablyInstance<
     async cancel(runId: string): Promise<void> {
       const run = await getRunOrThrow(runId)
       if (run.status === 'completed') {
-        throw new Error(`Cannot cancel completed run: ${runId}`)
+        throw new ConflictError(`Cannot cancel completed run: ${runId}`)
       }
       if (run.status === 'failed') {
-        throw new Error(`Cannot cancel failed run: ${runId}`)
+        throw new ConflictError(`Cannot cancel failed run: ${runId}`)
       }
       if (run.status === 'cancelled') {
-        throw new Error(`Cannot cancel already cancelled run: ${runId}`)
+        throw new ConflictError(`Cannot cancel already cancelled run: ${runId}`)
       }
       const wasPending = run.status === 'pending'
       const cancelled = await storage.cancelRun(runId, new Date().toISOString())
 
       if (!cancelled) {
         // Run transitioned to a terminal state between the check and the update
         const current = await getRunOrThrow(runId)
-        throw new Error(
+        throw new ConflictError(
           `Cannot cancel run ${runId}: status changed to ${current.status}`,
         )
       }
@@ -882,10 +888,10 @@ function createDurablyInstance<
     async deleteRun(runId: string): Promise<void> {
       const run = await getRunOrThrow(runId)
       if (run.status === 'pending') {
-        throw new Error(`Cannot delete pending run: ${runId}`)
+        throw new ConflictError(`Cannot delete pending run: ${runId}`)
       }
       if (run.status === 'leased') {
-        throw new Error(`Cannot delete leased run: ${runId}`)
+        throw new ConflictError(`Cannot delete leased run: ${runId}`)
       }
       await storage.deleteRun(runId)
 

packages/durably/src/errors.ts

@@ -20,6 +20,43 @@ export class LeaseLostError extends Error {
   }
 }
 
+/**
+ * Base class for errors that map to specific HTTP status codes.
+ * Used by the HTTP handler to return appropriate responses.
+ */
+export class DurablyError extends Error {
+  readonly statusCode: number
+  constructor(message: string, statusCode: number) {
+    super(message)
+    this.name = 'DurablyError'
+    this.statusCode = statusCode
+  }
+}
+
+/** 404 — Resource not found */
+export class NotFoundError extends DurablyError {
+  constructor(message: string) {
+    super(message, 404)
+    this.name = 'NotFoundError'
+  }
+}
+
+/** 400 — Invalid input or request */
+export class ValidationError extends DurablyError {
+  constructor(message: string) {
+    super(message, 400)
+    this.name = 'ValidationError'
+  }
+}
+
+/** 409 — Operation conflicts with current state */
+export class ConflictError extends DurablyError {
+  constructor(message: string) {
+    super(message, 409)
+    this.name = 'ConflictError'
+  }
+}
+
 /**
  * Extract error message from unknown error
  */

packages/durably/src/http.ts

@@ -29,7 +29,7 @@ export function jsonResponse(data: unknown, status = 200): Response {
  */
 export function errorResponse(
   message: string,
-  status: 400 | 404 | 500 = 500,
+  status: 400 | 404 | 409 | 500 = 500,
 ): Response {
   return jsonResponse({ error: message }, status)
 }

packages/durably/src/index.ts

@@ -69,7 +69,14 @@ export type {
 } from './storage'
 
 // Errors
-export { CancelledError, LeaseLostError } from './errors'
+export {
+  CancelledError,
+  ConflictError,
+  DurablyError,
+  LeaseLostError,
+  NotFoundError,
+  ValidationError,
+} from './errors'
 
 // Server
 export { createDurablyHandler } from './server'

packages/durably/src/job.ts

@@ -1,5 +1,6 @@
 import { type z, prettifyError } from 'zod'
 import type { JobDefinition } from './define-job'
+import { ValidationError } from './errors'
 import type { EventEmitter, LogData, ProgressData } from './events'
 import type { Run, RunFilter, Store } from './storage'
 
@@ -17,7 +18,9 @@ export function validateJobInputOrThrow<T>(
   const result = schema.safeParse(input)
   if (!result.success) {
     const prefix = context ? `${context}: ` : ''
-    throw new Error(`${prefix}Invalid input: ${prettifyError(result.error)}`)
+    throw new ValidationError(
+      `${prefix}Invalid input: ${prettifyError(result.error)}`,
+    )
   }
   return result.data
 }

packages/durably/src/server.ts

@@ -1,8 +1,8 @@
 import type { Durably } from './durably'
+import { DurablyError, getErrorMessage } from './errors'
 import type { AnyEventInput } from './events'
 import {
   errorResponse,
-  getErrorMessage,
   getRequiredQueryParam,
   jsonResponse,
   successResponse,
@@ -267,14 +267,20 @@ export function createDurablyHandler<
 
   // --- Shared helpers ---
 
-  /** Wrap handler with try/catch that re-throws Response and catches everything else as 500 */
+  /** Wrap handler with try/catch that maps DurablyError to proper HTTP status */
   async function withErrorHandling(
     fn: () => Promise<Response>,
   ): Promise<Response> {
     try {
       return await fn()
     } catch (error) {
       if (error instanceof Response) throw error
+      if (error instanceof DurablyError) {
+        return errorResponse(
+          error.message,
+          error.statusCode as 400 | 404 | 409 | 500,
+        )
+      }
       return errorResponse(getErrorMessage(error), 500)
     }
   }
@@ -323,14 +329,11 @@ export function createDurablyHandler<
         await auth.onTrigger(ctx as TContext, body)
       }
 
-      const run = await job.trigger(
-        (body.input ?? {}) as Record<string, unknown>,
-        {
-          idempotencyKey: body.idempotencyKey,
-          concurrencyKey: body.concurrencyKey,
-          labels: body.labels,
-        },
-      )
+      const run = await job.trigger(body.input as Record<string, unknown>, {
+        idempotencyKey: body.idempotencyKey,
+        concurrencyKey: body.concurrencyKey,
+        labels: body.labels,
+      })
 
       const response: TriggerResponse = { runId: run.id }
       return jsonResponse(response)

packages/durably/tests/shared/server.shared.ts

@@ -574,7 +574,7 @@ export function createServerTests(createDialect: () => Dialect) {
         expect(body.error).toBe('runId query parameter is required')
       })
 
-      it('returns 500 when retriggering a pending run', async () => {
+      it('returns 409 when retriggering a pending run', async () => {
         const d = durably.register({
           job: defineJob({
             name: 'retrigger-pending-test',
@@ -590,7 +590,7 @@ export function createServerTests(createDialect: () => Dialect) {
         )
 
         const response = await handler.handle(request, '/api/durably')
-        expect(response.status).toBe(500)
+        expect(response.status).toBe(409)
       })
     })
 
@@ -632,7 +632,7 @@ export function createServerTests(createDialect: () => Dialect) {
         expect(body.error).toBe('runId query parameter is required')
       })
 
-      it('returns 500 when cancelling completed run', async () => {
+      it('returns 409 when cancelling completed run', async () => {
         const d = durably.register({
           job: defineJob({
             name: 'cancel-completed-test',
@@ -657,7 +657,7 @@ export function createServerTests(createDialect: () => Dialect) {
         )
 
         const response = await handler.handle(request, '/api/durably')
-        expect(response.status).toBe(500)
+        expect(response.status).toBe(409)
       })
     })