Skip to content

Align failure-handling guidance with the Durable Execution categories - #5448

Draft
Duncanma wants to merge 1 commit into
duncan/durable-execution-content-15e64bfrom
duncan/durable-execution-failure-guidance
Draft

Duncanma wants to merge 1 commit into
duncan/durable-execution-content-15e64bfrom
duncan/durable-execution-failure-guidance

Conversation

@Duncanma

@Duncanma Duncanma commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

Summary

Aligns the failure-handling guidance with the Durable Execution categories: transient failures (one-time or intermittent), permanent failures, and negative results.

Stacked on the PR that adds /durable-execution. Retarget to main after it merges.

Changes

  • Error handling best practices.
    • "Intermittent" is now a sub-case of transient.
    • Added a Negative results section that lists the choices a Workflow has: return a value, raise a non-retryable failure, or wait and try again.
    • Moved "business rule violations" out of the permanent-failure list.
    • Added a note that failing an Activity fast doesn't have to fail the Workflow. The Workflow can wait for a fix, as in the Resumable Activity pattern.
  • Retry Policies.
    • Reduced the three failure types to two (transient, which includes intermittent, and permanent) and added a note on negative results.
    • The advice about correcting bad input now says the Workflow resumes, not restarts.
  • Python error handling. Same reclassification, applied to the prose only.
  • Application failures. Relates platform and application failures to the three categories. A failed call to an external service is often transient.
  • Tasks. The declined-card example now notes that failing the Workflow is a choice. The Workflow could wait for new payment details instead.
  • Detecting Workflow failures. Replaced an incorrect example of a Workflow Task that "checks a remote data source" (Workflow Tasks don't do I/O) with an accurate description of when a Workflow Task fails.

Code samples that model outcomes such as InsufficientFunds as non-retryable failures are unchanged. That remains a valid choice for handling negative results.

Verification

  • yarn build and yarn check-links were run on the combined stack.
  • vale --config .vale-ci.ini is clean on all touched files.

Reclassify failures as transient (one-time or intermittent), permanent,
or negative results:

- Error handling best practices: fold intermittent into transient, add
  a Negative results section, and note that a permanent Activity
  failure doesn't have to fail the Workflow
- Retry Policies, Python error handling, Application failures: same
  reclassification; business rule violations are negative results that
  code can choose to model as failures
- Tasks: note that the declined-card example is a choice, not the only
  option
- Detecting Workflow failures: replace an incorrect example of a
  Workflow Task that checks a remote data source
@vercel

vercel Bot commented Oct 7, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
temporal-documentation Ready Ready Preview Oct 7, 2026 9:27pm UTC

Request Review

@github-actions

github-actions Bot commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

📖 Docs PR preview links

This branch was successfully deployed

1 active deployment
Preview — 3ecb8c76 Deployed Oct 7, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant