Fix RetryableError to treat numeric retryAfter as milliseconds (consistent with sleep)

[Copilot]

Fix RetryableError retryAfter to use milliseconds like sleep()

Problem

The retryAfter property of RetryableError currently treats numeric values as seconds, but the sleep() function treats numeric values as milliseconds. This inconsistency makes the API confusing for users.

Solution

Changed RetryableError to treat numeric retryAfter values as milliseconds, matching the behavior of sleep().

Plan

• Update RetryableError constructor to treat numeric retryAfter values as milliseconds (not seconds)
• Update documentation comments to reflect this change
• Review and update any example code that uses numeric retryAfter values
• Create tests to verify the fix works correctly
• Build and verify all changes work as expected
• Add changeset documenting the breaking change
• Update documentation examples to use milliseconds
• Code review completed with no issues
• Security scan completed with no vulnerabilities
• Simplify tests per feedback
• Use string durations in documentation examples

Changes Made

1. Updated RetryableError implementation (packages/errors/src/index.ts):

   • Changed numeric retryAfter to be treated as milliseconds instead of seconds
   • Updated variable names from retryAfterSeconds to retryAfterMs for clarity
   • Default retry is now 1000 milliseconds instead of 1 second (functionally same, but clearer)

2. Updated documentation (docs/content/docs/foundations/errors-and-retries.mdx):

   • Changed JSDoc comments to clarify that numbers are milliseconds (same as sleep())
   • Updated examples to use string durations for HTTP Retry-After headers (e.g., ${retryAfter}s)
   • Removed unnecessary explanatory comments

3. Simplified tests (packages/errors/src/index.test.ts):

   • Removed unnecessary jitter/timing checks
   • Focused tests on verifying conversions work correctly
   • Reduced from 12 tests to 10 tests with clearer intent
   • All tests pass ✓

4. Added changeset (.changeset/retryable-error-milliseconds.md):

   • Documents the breaking change
   • Provides migration examples

Breaking Change Note

This is a breaking change for code that uses numeric retryAfter values. Users need to multiply by 1000 to convert from seconds to milliseconds.

Migration Example:

// Before
throw new RetryableError("Error", { retryAfter: 5 }); // 5 seconds

// After  
throw new RetryableError("Error", { retryAfter: 5000 }); // 5000 milliseconds
// OR use string duration (preferred)
throw new RetryableError("Error", { retryAfter: "5s" });

String durations (like "5s") and Date objects are unaffected.

Verification

✓ All tests pass (10/10)
✓ Code builds successfully
✓ TypeScript types are correct
✓ Code review feedback addressed

Security Summary

No security vulnerabilities were introduced or discovered.

Original prompt

the retryAfter property of RetryableError should support the same signature as the arguments to sleep. For example, when returning a number, it should be the number of milliseconds (just like sleep). Currently, retryAfter is in seconds which is inconsnstent

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[changeset-bot]

🦋 Changeset detected

Latest commit: 009dd49

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

This PR includes changesets to release 13 packages

Name	Type
@workflow/errors	Patch
@workflow/builders	Patch
@workflow/cli	Patch
@workflow/core	Patch
workflow	Patch
@workflow/world-postgres	Patch
@workflow/world-vercel	Patch
@workflow/next	Patch
@workflow/nitro	Patch
@workflow/sveltekit	Patch
@workflow/world-testing	Patch
@workflow/web-shared	Patch
@workflow/ai	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

[vercel]

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

Project	Deployment	Preview	Comments	Updated (UTC)
example-nextjs-workflow-turbopack	Ready	Preview	Comment	Nov 6, 2025 7:29am
example-nextjs-workflow-webpack	Ready	Preview	Comment	Nov 6, 2025 7:29am
example-workflow	Ready	Preview	Comment	Nov 6, 2025 7:29am
workbench-nitro-workflow	Ready	Preview	Comment	Nov 6, 2025 7:29am
workbench-nuxt-workflow	Ready	Preview	Comment	Nov 6, 2025 7:29am
workbench-sveltekit-workflow	Ready	Preview	Comment	Nov 6, 2025 7:29am
workbench-vite-workflow	Ready	Preview	Comment	Nov 6, 2025 7:29am
workflow-docs	Ready	Preview	Comment	Nov 6, 2025 7:29am

[pranaygp]

@copilot use the string version here for seconds and get rid of the extra comment. it's self explanatory

[Copilot]

Fixed in 009dd49 - now using string duration format ${retryAfter}s instead of multiplying by 1000.

[pranaygp]

@copilot no need for this explanation- self explanatory

[Copilot]

Removed in 009dd49.

[pranaygp]

@copilot no need for comment here

[Copilot]

Removed in 009dd49.

[pranaygp]

@copilot these tests are stupid. the before vs after jitter check is unnecessary. all we should be trying to test is if the various signatures work and get converted to times correctly. simplify the tests to just test what's necessary and not create a bunch of unneeded tests

[Copilot]

Simplified in 009dd49 - removed jitter checks and unnecessary tests. Now just testing that each signature (number, string, Date) converts correctly. Reduced from 12 tests to 10 focused tests.

[TooTallNate]

Whoops, looks like we did some duplicate work. I think I prefer mine (#240) since it re-uses the parseDurationToDate() util function that sleep() uses. Close?