EDU-3819: docs: tried to clarify the notes on failures (#3274)

* Added notes to failures page. * fix my broken anchor * some responses to Erica's comments * fix in resposne to Erica's comment * Sending to Erica --------- Co-authored-by: Erica Sadun <[email protected]>
temporalio · Jan 22, 2025 · 9c1e3fe · 9c1e3fe
1 parent 3b289cd
commit 9c1e3fe
Show file tree

Hide file tree

Showing 2 changed files with 9 additions and 7 deletions.
diff --git a/docs/encyclopedia/retry-policies.mdx b/docs/encyclopedia/retry-policies.mdx
@@ -18,7 +18,7 @@ import { RelatedReadContainer, RelatedReadItem } from '@site/src/components/rela
 A Retry Policy works in cooperation with the timeouts to provide fine controls to optimize the execution experience.
 
 A Retry Policy is a collection of attributes that instructs the Temporal Server how to retry a failure of a [Workflow Execution](/workflows#workflow-execution) or an [Activity Task Execution](/tasks#activity-task-execution).
-(Retry Policies do not apply to [Workflow Task Executions](/tasks#workflow-task-execution), which always retry indefinitely.)
+Note that Retry Policies do not apply to [Workflow Task Executions](/tasks#workflow-task-execution), which retry until the Workflow Execution Timeout, which is unlimited by default.
 
 Try out the [Activity retry simulator](/develop/activity-retry-simulator) to visiualize how a Retry Policy works.
 

diff --git a/docs/references/failures.mdx b/docs/references/failures.mdx
@@ -52,21 +52,22 @@ This is the only type of Temporal Failure created and thrown by user code.
 An error in a Workflow can cause either a **Workflow Task Failure** (the Task will be retried) or a **Workflow Execution Failure** (the Workflow is marked as failed).
 
 Only Workflow exceptions that are Temporal Failures cause the Workflow Execution to fail; all other exceptions cause the Workflow Task to fail and be retried (in Go, any error returned from the Workflow fails the Workflow Execution, and a panic fails the Workflow Task).
-Most types of Temporal Failures occur automatically, like a [Cancelled Failure](#cancelled-failure) when the Workflow is Cancelled or an [Activity Failure](#activity-failure) when an Activity Fails.
-You can also explicitly fail the Workflow Execution by throwing an Application Failure (returning any error in Go).
+Most types of Temporal Failures are raised by the Temporal Service, like a [Cancelled Failure](#cancelled-failure) when the Workflow is Cancelled or an [Activity Failure](#activity-failure) when an Activity fails.
+In contrast, you can explicitly fail the Workflow Execution by throwing an Application Failure (returning any error in Go) in Workflow Definition code.
 
 #### Workflow Task Failures
 
 A **Workflow Task Failure** is an unexpected situation failing to process a Workflow Task.
-This could be triggered by raising an exception in your Workflow code.
+This could be triggered by a non-Temporal exception being raised (panicking in Go) in your Workflow code.
 Any exception that does not extend Temporal's `FailureError` exception is considered a Workflow Task Failure.
-These types of failures will cause the Workflow Task to be retried.
+These types of failures will cause the Workflow Task to be retried until the
+Workflow Execution Timeout, which is unlimited by default.
 
 #### Workflow Execution Failures
 
 An `ApplicationError`, an extension of `FailureError`, can be raised in a Workflow to fail the Workflow Execution.
 Workflow Execution Failures put the Workflow Execution into the "Failed" state and no more attempts will be made in progressing this execution.
-If you are creating custom exceptions you would either need to extend the `ApplicationError` class—a child class of `FailureError`— or explicitly state that this exception is a Workflow Execution Failure by raising a new `ApplicationError`.
+If you are creating custom exceptions you would need to extend the [`ApplicationError`](https://docs.temporal.io/references/failures#application-failure) class—a child class of [`FailureError`](https://docs.temporal.io/references/failures#temporal-failure).
 
 ### Errors in Activities
 
@@ -82,7 +83,8 @@ During conversion, the following Application Failure fields are set:
 - `next_retry_delay` is left unset.
 - call stack is copied.
 
-When an [Activity Execution](/activities#activity-execution) fails, the Application Failure from the last Activity Task is the `cause` field of the [ActivityFailure](#activity-failure) thrown in the Workflow.
+When an [Activity Execution](/activities#activity-execution) fails, the Application Failure from the last Activity Task is the `cause` field of the [ActivityFailure](#activity-failure).
+This ActivityFailure is thrown by the Workflow's call to the Activity, and it can be handled in the Workflow Definition.
 
 ### Errors in Nexus Operations