feat: add semantic error types to replace HTTP status code checks in runtime

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: pranaygp

.changeset/semantic-world-errors.md

@@ -0,0 +1,9 @@
+---
+"@workflow/errors": patch
+"@workflow/core": patch
+"@workflow/world-local": patch
+"@workflow/world-vercel": patch
+"@workflow/world-postgres": patch
+---
+
+Replace HTTP status code checks with semantic error types (EntityConflictError, RunExpiredError, ThrottleError)

packages/core/src/runtime.ts

@@ -1,6 +1,7 @@
 import {
+  EntityConflictError,
   RUN_ERROR_CODES,
-  WorkflowAPIError,
+  RunExpiredError,
   WorkflowRuntimeError,
 } from '@workflow/errors';
 import { classifyRunError } from './classify-error.js';
@@ -195,8 +196,8 @@ export function workflowEntrypoint(
                       );
                     } catch (failErr) {
                       if (
-                        WorkflowAPIError.is(failErr) &&
-                        (failErr.status === 409 || failErr.status === 410)
+                        EntityConflictError.is(failErr) ||
+                        RunExpiredError.is(failErr)
                       ) {
                         return;
                       }
@@ -269,7 +270,7 @@ export function workflowEntrypoint(
                     // Add the event to the events array so the workflow can see it
                     events.push(result.event!);
                   } catch (err) {
-                    if (WorkflowAPIError.is(err) && err.status === 409) {
+                    if (EntityConflictError.is(err)) {
                       runtimeLogger.info('Wait already completed, skipping', {
                         workflowRunId: runId,
                         correlationId: waitEvent.correlationId,
@@ -393,8 +394,8 @@ export function workflowEntrypoint(
                     );
                   } catch (failErr) {
                     if (
-                      WorkflowAPIError.is(failErr) &&
-                      (failErr.status === 409 || failErr.status === 410)
+                      EntityConflictError.is(failErr) ||
+                      RunExpiredError.is(failErr)
                     ) {
                       runtimeLogger.info(
                         'Tried failing workflow run, but run has already finished.',
@@ -440,8 +441,8 @@ export function workflowEntrypoint(
                   );
                 } catch (err) {
                   if (
-                    WorkflowAPIError.is(err) &&
-                    (err.status === 409 || err.status === 410)
+                    EntityConflictError.is(err) ||
+                    RunExpiredError.is(err)
                   ) {
                     runtimeLogger.info(
                       'Tried completing workflow run, but run has already finished.',

packages/core/src/runtime/runs.test.ts

@@ -1,4 +1,4 @@
-import { WorkflowAPIError, WorkflowRunNotFoundError } from '@workflow/errors';
+import { EntityConflictError, WorkflowAPIError, WorkflowRunNotFoundError } from '@workflow/errors';
 import type { Event, World } from '@workflow/world';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
@@ -64,9 +64,7 @@ describe('wakeUpRun', () => {
       },
     ];
 
-    const conflict = new WorkflowAPIError('Wait already completed', {
-      status: 409,
-    });
+    const conflict = new EntityConflictError('Wait already completed');
 
     const world = createMockWorld({ events, createError: conflict });
     const result = await wakeUpRun(world, 'wrun_123');

packages/core/src/runtime/runs.ts

@@ -1,4 +1,4 @@
-import { WorkflowAPIError } from '@workflow/errors';
+import { EntityConflictError } from '@workflow/errors';
 import {
   type Event,
   isLegacySpecVersion,
@@ -192,7 +192,7 @@ export async function wakeUpRun(
         await world.events.create(runId, eventData, { v1Compat: compatMode });
         stoppedCount++;
       } catch (err) {
-        if (WorkflowAPIError.is(err) && err.status === 409) {
+        if (EntityConflictError.is(err)) {
           stoppedCount++;
         } else {
           errors.push(err instanceof Error ? err : new Error(String(err)));

packages/core/src/runtime/step-handler.test.ts

@@ -1,4 +1,4 @@
-import { WorkflowAPIError } from '@workflow/errors';
+import { EntityConflictError, WorkflowAPIError } from '@workflow/errors';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 // Use vi.hoisted so these are available in mock factories
@@ -248,9 +248,8 @@ describe('step-handler 409 handling', () => {
           if (event.eventType === 'step_completed') {
             callCount++;
             return Promise.reject(
-              new WorkflowAPIError(
-                'Cannot complete step because it is already completed',
-                { status: 409 }
+              new EntityConflictError(
+                'Cannot complete step because it is already completed'
               )
             );
           }
@@ -300,9 +299,8 @@ describe('step-handler 409 handling', () => {
           }
           if (event.eventType === 'step_failed') {
             return Promise.reject(
-              new WorkflowAPIError(
-                'Cannot fail step because it is already completed',
-                { status: 409 }
+              new EntityConflictError(
+                'Cannot fail step because it is already completed'
               )
             );
           }
@@ -347,9 +345,8 @@ describe('step-handler 409 handling', () => {
           }
           if (event.eventType === 'step_failed') {
             return Promise.reject(
-              new WorkflowAPIError(
-                'Cannot fail step because it is already completed',
-                { status: 409 }
+              new EntityConflictError(
+                'Cannot fail step because it is already completed'
               )
             );
           }
@@ -397,9 +394,8 @@ describe('step-handler 409 handling', () => {
           }
           if (event.eventType === 'step_retrying') {
             return Promise.reject(
-              new WorkflowAPIError(
-                'Cannot retry step because it is already completed',
-                { status: 409 }
+              new EntityConflictError(
+                'Cannot retry step because it is already completed'
               )
             );
           }