refactor: replace HTTP status code checks with semantic error types by pranaygp · Pull Request #1342 · vercel/workflow

pranaygp · 2026-03-12T05:42:49Z

Summary

Replaces the pattern of catching WorkflowAPIError with HTTP status codes (409, 410, 429) in the runtime with semantic error types that each world implementation throws directly. This removes the coupling between the runtime and HTTP transport semantics.

Stacked on #1340 → #1339

Problem

The runtime had ~18 places doing this:

if (WorkflowAPIError.is(err) && err.status === 409) {
  // entity already in terminal state, skip
}

This is wrong because:

HTTP status codes are a world-vercel implementation detail leaking into the runtime
world-local and world-postgres had to fake HTTP status codes (new WorkflowAPIError('...', { status: 409 })) to match
The runtime shouldn't know about HTTP — it should handle semantic states

Solution

New semantic error types (`@workflow/errors`)

Error	Replaces	Meaning
`EntityConflictError`	`status === 409`	Entity already in terminal state (run/step/wait finished)
`RunExpiredError`	`status === 410`	Run has been cleaned up or expired
`ThrottleError`	`status === 429`	Rate limited, carries `retryAfter`

All follow the existing HookNotFoundError / WorkflowRunNotFoundError pattern with .is() static method.

World implementations updated

world-vercel: makeRequest() maps HTTP 409 → EntityConflictError, 410 → RunExpiredError, 429 → ThrottleError at the throw site
world-local: All WorkflowAPIError({ status: 409 }) → EntityConflictError, etc.
world-postgres: Same pattern

Runtime updated

All ~18 catch sites now use semantic checks:

// Before
if (WorkflowAPIError.is(err) && err.status === 409) { ... }

// After
if (EntityConflictError.is(err)) { ... }

Files touched: runtime.ts, step-handler.ts, suspension-handler.ts, helpers.ts, runs.ts

`WorkflowAPIError` retained as catch-all

WorkflowAPIError remains for genuinely unexpected HTTP errors. The runtime no longer inspects .status on it.

Test plan

Build passes (all 27 packages)
Typecheck passes
All 478 core unit tests pass
All 220 world-local tests pass
Updated test files: helpers.test.ts, step-handler.test.ts, runs.test.ts
E2E tests (to be run on CI)

🤖 Generated with Claude Code

vercel · 2026-03-12T05:42:55Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
example-nextjs-workflow-turbopack	Ready	Preview, Comment	Mar 18, 2026 2:10am
example-nextjs-workflow-webpack	Ready	Preview, Comment	Mar 18, 2026 2:10am
example-workflow	Ready	Preview, Comment	Mar 18, 2026 2:10am
workbench-astro-workflow	Ready	Preview, Comment	Mar 18, 2026 2:10am
workbench-express-workflow	Ready	Preview, Comment	Mar 18, 2026 2:10am
workbench-fastify-workflow	Ready	Preview, Comment	Mar 18, 2026 2:10am
workbench-hono-workflow	Ready	Preview, Comment	Mar 18, 2026 2:10am
workbench-nitro-workflow	Ready	Preview, Comment	Mar 18, 2026 2:10am
workbench-nuxt-workflow	Ready	Preview, Comment	Mar 18, 2026 2:10am
workbench-sveltekit-workflow	Ready	Preview, Comment	Mar 18, 2026 2:10am
workbench-vite-workflow	Ready	Preview, Comment	Mar 18, 2026 2:10am
workflow-docs	Ready	Preview, Comment, Open in v0	Mar 18, 2026 2:10am
workflow-nest	Ready	Preview, Comment	Mar 18, 2026 2:10am
workflow-swc-playground	Ready	Preview, Comment	Mar 18, 2026 2:10am

github-actions · 2026-03-12T05:43:00Z

🧪 E2E Test Results

❌ Some tests failed

Summary

	Passed	Failed	Skipped	Total
✅ ▲ Vercel Production	758	0	67	825
✅ 💻 Local Development	782	0	118	900
✅ 📦 Local Production	782	0	118	900
❌ 🐘 Local Postgres	781	1	118	900
✅ 🪟 Windows	72	0	3	75
❌ 🌍 Community Worlds	118	56	15	189
✅ 📋 Other	198	0	27	225
Total	3491	57	466	4014

❌ Failed Tests

🐘 Local Postgres (1 failed)

fastify-stable (1 failed):

webhookWorkflow

🌍 Community Worlds (56 failed)

mongodb (3 failed):

hookWorkflow is not resumable via public webhook endpoint
webhookWorkflow
concurrent hook token conflict - two workflows cannot use the same hook token simultaneously

redis (2 failed):

hookWorkflow is not resumable via public webhook endpoint
concurrent hook token conflict - two workflows cannot use the same hook token simultaneously

turso (51 failed):

addTenWorkflow
addTenWorkflow
wellKnownAgentWorkflow (.well-known/agent)
should work with react rendering in step
promiseAllWorkflow
promiseRaceWorkflow
promiseAnyWorkflow
importedStepOnlyWorkflow
hookWorkflow
hookWorkflow is not resumable via public webhook endpoint
webhookWorkflow
sleepingWorkflow
parallelSleepWorkflow
nullByteWorkflow
workflowAndStepMetadataWorkflow
fetchWorkflow
promiseRaceStressTestWorkflow
error handling error propagation workflow errors nested function calls preserve message and stack trace
error handling error propagation workflow errors cross-file imports preserve message and stack trace
error handling error propagation step errors basic step error preserves message and stack trace
error handling error propagation step errors cross-file step error preserves message and function names in stack
error handling retry behavior regular Error retries until success
error handling retry behavior FatalError fails immediately without retries
error handling retry behavior RetryableError respects custom retryAfter delay
error handling retry behavior maxRetries=0 disables retries
error handling catchability FatalError can be caught and detected with FatalError.is()
hookCleanupTestWorkflow - hook token reuse after workflow completion
concurrent hook token conflict - two workflows cannot use the same hook token simultaneously
hookDisposeTestWorkflow - hook token reuse after explicit disposal while workflow still running
stepFunctionPassingWorkflow - step function references can be passed as arguments (without closure vars)
stepFunctionWithClosureWorkflow - step function with closure variables passed as argument
closureVariableWorkflow - nested step functions with closure variables
spawnWorkflowFromStepWorkflow - spawning a child workflow using start() inside a step
health check (queue-based) - workflow and step endpoints respond to health check messages
pathsAliasWorkflow - TypeScript path aliases resolve correctly
Calculator.calculate - static workflow method using static step methods from another class
AllInOneService.processNumber - static workflow method using sibling static step methods
ChainableService.processWithThis - static step methods using this to reference the class
thisSerializationWorkflow - step function invoked with .call() and .apply()
customSerializationWorkflow - custom class serialization with WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE
instanceMethodStepWorkflow - instance methods with "use step" directive
crossContextSerdeWorkflow - classes defined in step code are deserializable in workflow context
stepFunctionAsStartArgWorkflow - step function reference passed as start() argument
cancelRun - cancelling a running workflow
cancelRun via CLI - cancelling a running workflow
pages router addTenWorkflow via pages router
pages router promiseAllWorkflow via pages router
pages router sleepingWorkflow via pages router
hookWithSleepWorkflow - hook payloads delivered correctly with concurrent sleep
sleepInLoopWorkflow - sleep inside loop with steps actually delays each iteration
sleepWithSequentialStepsWorkflow - sequential steps work with concurrent sleep (control)

Details by Category

✅ ▲ Vercel Production

App	Passed	Skipped
✅ astro	68	7
✅ example	68	7
✅ express	68	7
✅ fastify	68	7
✅ hono	68	7
✅ nextjs-turbopack	73	2
✅ nextjs-webpack	73	2
✅ nitro	68	7
✅ nuxt	68	7
✅ sveltekit	68	7
✅ vite	68	7

✅ 💻 Local Development

App	Passed	Skipped
✅ astro-stable	66	9
✅ express-stable	66	9
✅ fastify-stable	66	9
✅ hono-stable	66	9
✅ nextjs-turbopack-canary	55	20
✅ nextjs-turbopack-stable	72	3
✅ nextjs-webpack-canary	55	20
✅ nextjs-webpack-stable	72	3
✅ nitro-stable	66	9
✅ nuxt-stable	66	9
✅ sveltekit-stable	66	9
✅ vite-stable	66	9

✅ 📦 Local Production

App	Passed	Skipped
✅ astro-stable	66	9
✅ express-stable	66	9
✅ fastify-stable	66	9
✅ hono-stable	66	9
✅ nextjs-turbopack-canary	55	20
✅ nextjs-turbopack-stable	72	3
✅ nextjs-webpack-canary	55	20
✅ nextjs-webpack-stable	72	3
✅ nitro-stable	66	9
✅ nuxt-stable	66	9
✅ sveltekit-stable	66	9
✅ vite-stable	66	9

❌ 🐘 Local Postgres

App	Passed	Failed	Skipped
✅ astro-stable	66	0	9
✅ express-stable	66	0	9
❌ fastify-stable	65	1	9
✅ hono-stable	66	0	9
✅ nextjs-turbopack-canary	55	0	20
✅ nextjs-turbopack-stable	72	0	3
✅ nextjs-webpack-canary	55	0	20
✅ nextjs-webpack-stable	72	0	3
✅ nitro-stable	66	0	9
✅ nuxt-stable	66	0	9
✅ sveltekit-stable	66	0	9
✅ vite-stable	66	0	9

✅ 🪟 Windows

App	Passed	Failed	Skipped
✅ nextjs-turbopack	72	0	3

❌ 🌍 Community Worlds

App	Passed	Failed	Skipped
✅ mongodb-dev	3	0	2
❌ mongodb	52	3	3
✅ redis-dev	3	0	2
❌ redis	53	2	3
✅ turso-dev	3	0	2
❌ turso	4	51	3

✅ 📋 Other

App	Passed	Skipped
✅ e2e-local-dev-nest-stable	66	9
✅ e2e-local-postgres-nest-stable	66	9
✅ e2e-local-prod-nest-stable	66	9

📋 View full workflow run

❌ Some E2E test jobs failed:

Vercel Prod: success
Local Dev: success
Local Prod: success
Local Postgres: failure
Windows: success

Check the workflow run for details.

pranaygp · 2026-03-12T06:08:33Z

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

This stack of pull requests is managed by Graphite. Learn more about stacking.

changeset-bot · 2026-03-12T18:59:24Z

🦋 Changeset detected

Latest commit: cb18ce3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 20 packages

Name	Type
@workflow/errors	Patch
@workflow/core	Patch
@workflow/world-local	Patch
@workflow/world-vercel	Patch
@workflow/world-postgres	Patch
@workflow/builders	Patch
@workflow/cli	Patch
workflow	Patch
@workflow/next	Patch
@workflow/nitro	Patch
@workflow/vitest	Patch
@workflow/web-shared	Patch
@workflow/world-testing	Patch
@workflow/astro	Patch
@workflow/nest	Patch
@workflow/rollup	Patch
@workflow/sveltekit	Patch
@workflow/vite	Patch
@workflow/ai	Patch
@workflow/nuxt	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

changeset-bot · 2026-03-12T18:59:24Z

🦋 Changeset detected

Latest commit: 2841381

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 20 packages

Name	Type
@workflow/errors	Patch
@workflow/core	Patch
@workflow/world-local	Patch
@workflow/world-vercel	Patch
@workflow/world-postgres	Patch
@workflow/builders	Patch
@workflow/cli	Patch
workflow	Patch
@workflow/next	Patch
@workflow/nitro	Patch
@workflow/vitest	Patch
@workflow/web-shared	Patch
@workflow/world-testing	Patch
@workflow/astro	Patch
@workflow/nest	Patch
@workflow/rollup	Patch
@workflow/sveltekit	Patch
@workflow/vite	Patch
@workflow/ai	Patch
@workflow/nuxt	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

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

Copilot

Pull request overview

Refactors error handling across the core runtime and world implementations to replace runtime-side HTTP status code branching (409/410/429) with semantic error types emitted by worlds, reducing coupling to HTTP transport details.

Changes:

Add new semantic error classes in @workflow/errors: EntityConflictError, RunExpiredError, ThrottleError.
Update world-vercel to map HTTP 409/410/429 to those semantic errors at the request boundary.
Update world-local, world-postgres, and @workflow/core runtime call sites to throw/catch semantic errors instead of WorkflowAPIError.status.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/world-vercel/src/utils.ts	Map HTTP 409/410/429 responses to semantic errors in `makeRequest()`
packages/world-postgres/src/storage.ts	Replace storage-layer `WorkflowAPIError({status:409/410})` with semantic errors
packages/world-local/src/storage/events-storage.ts	Replace local storage `WorkflowAPIError({status:409/410})` with semantic errors
packages/world-local/src/fs.ts	Use `EntityConflictError` for write conflicts instead of HTTP-encoded errors
packages/errors/src/index.ts	Introduce semantic error classes for conflict/expired/throttle cases
packages/core/src/runtime/suspension-handler.ts	Replace runtime checks for 409/410 with semantic errors in suspension flow
packages/core/src/runtime/step-handler.ts	Replace runtime checks for 409/410/429 with semantic errors in step processing
packages/core/src/runtime/step-handler.test.ts	Update tests to throw `EntityConflictError` instead of `WorkflowAPIError(409)`
packages/core/src/runtime/runs.ts	Use `EntityConflictError` for wake-up conflict handling
packages/core/src/runtime/runs.test.ts	Update tests to use `EntityConflictError`
packages/core/src/runtime.ts	Replace runtime status checks (409/410) with semantic error guards
.changeset/semantic-world-errors.md	Publish patch bumps for affected packages

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

packages/errors/src/index.ts

+ * Thrown when attempting to operate on a run that has been cleaned up or expired.
+ * Replaces WorkflowAPIError with status 410.


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

+            // 425 Too Early: retryAfter timestamp not reached yet
+            // Return timeout to queue so it retries later
+            if (WorkflowAPIError.is(err) && err.status === 425) {
+              // Parse retryAfter from error response meta


packages/core/src/runtime/suspension-handler.ts

+          } else if (WorkflowAPIError.is(err) && err.status === 404) {
+            // Hook may have already been disposed or never created
+            runtimeLogger.info('Hook not found for disposal, continuing', {
+              workflowRunId: runId,
+              correlationId: queueItem.correlationId,
+              message: err.message,
+            });


packages/errors/src/index.ts

 }

+/**
+ * Thrown when attempting to modify an entity that is already in a terminal state.


vercel bot deployed to Preview – workflow-swc-playground March 12, 2026 05:43 View deployment

vercel bot deployed to Preview – workbench-nitro-workflow March 12, 2026 05:43 View deployment

vercel bot deployed to Preview – workbench-hono-workflow March 12, 2026 05:43 View deployment

vercel bot deployed to Preview – workbench-vite-workflow March 12, 2026 05:43 View deployment

vercel bot deployed to Preview – workbench-express-workflow March 12, 2026 05:43 View deployment

vercel bot deployed to Preview – workbench-sveltekit-workflow March 12, 2026 05:43 View deployment

vercel bot deployed to Preview – workbench-astro-workflow March 12, 2026 05:43 View deployment

vercel bot deployed to Preview – workbench-fastify-workflow March 12, 2026 05:43 View deployment

vercel bot deployed to Preview – workflow-nest March 12, 2026 05:43 View deployment

vercel bot deployed to Preview – example-workflow March 12, 2026 05:43 View deployment

vercel bot deployed to Preview – workbench-nuxt-workflow March 12, 2026 05:43 View deployment

vercel bot deployed to Preview – example-nextjs-workflow-turbopack March 12, 2026 05:44 View deployment

vercel bot deployed to Preview – example-nextjs-workflow-webpack March 12, 2026 05:44 View deployment

vercel bot deployed to Preview – workflow-docs March 12, 2026 05:44 View deployment

This was referenced Mar 12, 2026

fix: separate infrastructure vs user code error handling #1339

Merged

feat: classify run failure error codes and improve error logging #1340

Open

feat: enforce max queue deliveries in handlers with graceful failure #1344

Draft

pranaygp force-pushed the pgp/run-failed-schema-vailidation-error branch from 8480225 to 6655edc Compare March 12, 2026 18:59

pranaygp force-pushed the pgp/semantic-world-errors branch from 1563db7 to 2841381 Compare March 12, 2026 18:59

vercel bot deployed to Preview – workflow-swc-playground March 12, 2026 19:00 View deployment

vercel bot deployed to Preview – workbench-express-workflow March 12, 2026 19:00 View deployment

vercel bot deployed to Preview – workbench-nitro-workflow March 12, 2026 19:00 View deployment

vercel bot deployed to Preview – workbench-sveltekit-workflow March 12, 2026 19:00 View deployment

vercel bot deployed to Preview – workbench-astro-workflow March 12, 2026 19:00 View deployment

vercel bot deployed to Preview – workbench-vite-workflow March 12, 2026 19:00 View deployment

vercel bot deployed to Preview – example-nextjs-workflow-turbopack March 13, 2026 01:09 View deployment

vercel bot deployed to Preview – workbench-sveltekit-workflow March 13, 2026 01:09 View deployment

vercel bot deployed to Preview – example-nextjs-workflow-webpack March 13, 2026 01:10 View deployment

vercel bot deployed to Preview – workflow-docs March 13, 2026 01:10 View deployment

pranaygp force-pushed the pgp/run-failed-schema-vailidation-error branch from e7068bf to e019085 Compare March 17, 2026 19:35

pranaygp force-pushed the pgp/semantic-world-errors branch from 90bd273 to 0a9c6f7 Compare March 17, 2026 19:35

vercel bot deployed to Preview – workflow-swc-playground March 17, 2026 19:36 View deployment

vercel bot deployed to Preview – workbench-vite-workflow March 17, 2026 19:36 View deployment

vercel bot deployed to Preview – workbench-nitro-workflow March 17, 2026 19:37 View deployment

vercel bot deployed to Preview – workbench-fastify-workflow March 17, 2026 19:37 View deployment

vercel bot deployed to Preview – workbench-hono-workflow March 17, 2026 19:37 View deployment

vercel bot deployed to Preview – workbench-express-workflow March 17, 2026 19:37 View deployment

vercel bot deployed to Preview – workbench-astro-workflow March 17, 2026 19:37 View deployment

vercel bot deployed to Preview – workflow-nest March 17, 2026 19:37 View deployment

vercel bot deployed to Preview – workbench-sveltekit-workflow March 17, 2026 19:37 View deployment

vercel bot deployed to Preview – workbench-nuxt-workflow March 17, 2026 19:37 View deployment

vercel bot deployed to Preview – example-workflow March 17, 2026 19:37 View deployment

vercel bot deployed to Preview – example-nextjs-workflow-turbopack March 17, 2026 19:37 View deployment

vercel bot deployed to Preview – workflow-docs March 17, 2026 19:37 View deployment

vercel bot deployed to Preview – example-nextjs-workflow-webpack March 17, 2026 19:37 View deployment

pranaygp force-pushed the pgp/run-failed-schema-vailidation-error branch 6 times, most recently from 256bb01 to 1f26e4e Compare March 18, 2026 01:59

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

cb18ce3

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

pranaygp force-pushed the pgp/semantic-world-errors branch from 0a9c6f7 to cb18ce3 Compare March 18, 2026 02:08

vercel bot deployed to Preview – workflow-swc-playground March 18, 2026 02:09 View deployment

Copilot AI reviewed Mar 18, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor: replace HTTP status code checks with semantic error types#1342

refactor: replace HTTP status code checks with semantic error types#1342
pranaygp wants to merge 1 commit intopgp/run-failed-schema-vailidation-errorfrom
pgp/semantic-world-errors

pranaygp commented Mar 12, 2026

Uh oh!

vercel bot commented Mar 12, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 12, 2026 •

edited

Loading

Uh oh!

pranaygp commented Mar 12, 2026 •

edited

Loading

Uh oh!

changeset-bot bot commented Mar 12, 2026 •

edited

Loading

Uh oh!

changeset-bot bot commented Mar 12, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		* Thrown when attempting to operate on a run that has been cleaned up or expired.
		* Replaces WorkflowAPIError with status 410.

Conversation

pranaygp commented Mar 12, 2026

Summary

Problem

Solution

New semantic error types (@workflow/errors)

World implementations updated

Runtime updated

WorkflowAPIError retained as catch-all

Test plan

Uh oh!

vercel bot commented Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🧪 E2E Test Results

Summary

❌ Failed Tests

Details by Category

Uh oh!

pranaygp commented Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

changeset-bot bot commented Mar 12, 2026

🦋 Changeset detected

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

New semantic error types (`@workflow/errors`)

`WorkflowAPIError` retained as catch-all

vercel bot commented Mar 12, 2026 •

edited

Loading

github-actions bot commented Mar 12, 2026 •

edited

Loading

pranaygp commented Mar 12, 2026 •

edited

Loading

changeset-bot bot commented Mar 12, 2026 •

edited

Loading