Add HandlerErrorRetryBehavior (#551)

Author: bergundy

openapi/openapiv2.json

@@ -8967,6 +8967,10 @@
         },
         "failure": {
           "$ref": "#/definitions/apinexusv1Failure"
+        },
+        "retryBehavior": {
+          "$ref": "#/definitions/v1NexusHandlerErrorRetryBehavior",
+          "description": "Retry behavior, defaults to the retry behavior of the error type as defined in the spec."
         }
       }
     },
@@ -9756,12 +9760,26 @@
       },
       "description": "NewWorkflowExecutionInfo is a shared message that encapsulates all the\nrequired arguments to starting a workflow in different contexts."
     },
+    "v1NexusHandlerErrorRetryBehavior": {
+      "type": "string",
+      "enum": [
+        "NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_UNSPECIFIED",
+        "NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_RETRYABLE",
+        "NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_NON_RETRYABLE"
+      ],
+      "default": "NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_UNSPECIFIED",
+      "description": "NexusHandlerErrorRetryBehavior allows nexus handlers to explicity set the retry behavior of a HandlerError. If not\nspecified, retry behavior is determined from the error type. For example internal errors are not retryable by default\nunless specified otherwise.\n\n - NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_RETRYABLE: A handler error is explicitly marked as retryable.\n - NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_NON_RETRYABLE: A handler error is explicitly marked as non-retryable."
+    },
     "v1NexusHandlerFailureInfo": {
       "type": "object",
       "properties": {
         "type": {
           "type": "string",
           "description": "The Nexus error type as defined in the spec:\nhttps://github.com/nexus-rpc/api/blob/main/SPEC.md#predefined-handler-errors."
+        },
+        "retryBehavior": {
+          "$ref": "#/definitions/v1NexusHandlerErrorRetryBehavior",
+          "description": "Retry behavior, defaults to the retry behavior of the error type as defined in the spec."
         }
       }
     },

openapi/openapiv3.yaml

@@ -7277,6 +7277,14 @@ components:
           description: |-
             The Nexus error type as defined in the spec:
              https://github.com/nexus-rpc/api/blob/main/SPEC.md#predefined-handler-errors.
+        retryBehavior:
+          enum:
+            - NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_UNSPECIFIED
+            - NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_RETRYABLE
+            - NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_NON_RETRYABLE
+          type: string
+          description: Retry behavior, defaults to the retry behavior of the error type as defined in the spec.
+          format: enum
     NexusOperationCancelRequestedEventAttributes:
       type: object
       properties:

temporal/api/enums/v1/nexus.proto

@@ -0,0 +1,42 @@
+// The MIT License
+//
+// Copyright (c) 2025 Temporal Technologies Inc. All rights reserved.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
+syntax = "proto3";
+
+package temporal.api.enums.v1;
+
+option go_package = "go.temporal.io/api/enums/v1;enums";
+option java_package = "io.temporal.api.enums.v1";
+option java_multiple_files = true;
+option java_outer_classname = "NexusProto";
+option ruby_package = "Temporalio::Api::Enums::V1";
+option csharp_namespace = "Temporalio.Api.Enums.V1";
+
+// NexusHandlerErrorRetryBehavior allows nexus handlers to explicity set the retry behavior of a HandlerError. If not
+// specified, retry behavior is determined from the error type. For example internal errors are not retryable by default
+// unless specified otherwise.
+enum NexusHandlerErrorRetryBehavior {
+    NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_UNSPECIFIED = 0;
+    // A handler error is explicitly marked as retryable.
+    NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_RETRYABLE = 1;
+    // A handler error is explicitly marked as non-retryable.
+    NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_NON_RETRYABLE = 2;
+}
+

temporal/api/failure/v1/message.proto

@@ -33,6 +33,7 @@ option csharp_namespace = "Temporalio.Api.Failure.V1";
 
 import "temporal/api/common/v1/message.proto";
 import "temporal/api/enums/v1/workflow.proto";
+import "temporal/api/enums/v1/nexus.proto";
 
 import "google/protobuf/duration.proto";
 
@@ -106,6 +107,8 @@ message NexusHandlerFailureInfo {
     // The Nexus error type as defined in the spec:
     // https://github.com/nexus-rpc/api/blob/main/SPEC.md#predefined-handler-errors.
     string type = 1;
+    // Retry behavior, defaults to the retry behavior of the error type as defined in the spec.
+    temporal.api.enums.v1.NexusHandlerErrorRetryBehavior retry_behavior = 2;
 }
 
 message Failure {

temporal/api/nexus/v1/message.proto

@@ -31,6 +31,7 @@ option csharp_namespace = "Temporalio.Api.Nexus.V1";
 
 import "google/protobuf/timestamp.proto";
 import "temporal/api/common/v1/message.proto";
+import "temporal/api/enums/v1/nexus.proto";
 
 // A general purpose failure message.
 // See: https://github.com/nexus-rpc/api/blob/main/SPEC.md#failure
@@ -45,6 +46,8 @@ message HandlerError {
     // See https://github.com/nexus-rpc/api/blob/main/SPEC.md#predefined-handler-errors.
     string error_type = 1;
     Failure failure = 2;
+    // Retry behavior, defaults to the retry behavior of the error type as defined in the spec.
+    temporal.api.enums.v1.NexusHandlerErrorRetryBehavior retry_behavior = 3;
 }
 
 message UnsuccessfulOperationError {