Handling Exceptions

Action exceptions

Failures of Action states in the flow are exposed via Exceptions which, as described in the Action state documentation, can be handled via a Catch property on the Action state. There are three forms of exceptions that impact an action execution:

  • ActionUnableToRun: This exception indicates that the initial attempt to run the action failed and no action whatsoever was initiated. The output of the exception contains the error structure returned by the action. This condition will always result in an exception.

  • ActionFailedException: This indicates that the action was able initiated but during execution the action was considered to have failed by the return of an action status with the value FAILED. This exception will only be raised if the property ExceptionOnActionFailure is set to true. This allows the action failure to be handled by checking the result or by causing an exception. Either approach is valid and different users and different use cases may lend themselves to either approach. In either case, the output will contain the same action status structure a completed action will contain, but the status value will necessarily be FAILED.

  • ActionTimeout: When the WaitTime for an Action state is exceeded, this exception will be raised. The status of the most recent poll of the Action will be contained within the body of the exception.

Exception information

By default, the flow state is overwritten with the error information when an exception is encountered.

If a Catch clause is used to recover from an exception, it is recommended that flow authors use the ResultPath to prevent error information from overwriting the flow state.

For example, if the flow state contains this information:

{
  "endpoint_id": "00000000-0000-0000-0000-000000000000",
  "path": "/~/"
}

and an error is encountered in a state with this Catch clause:

{
  "Catch": [
    {
      "ErrorEquals": [
        "ActionUnableToRun"
      ],
      "ResultPath": "$.FailureInfo",
      "Next": "HandleError"
    },
    {
      "ErrorEquals": [
        "ActionFailedException"
      ],
      "Next": "HandleError"
    }
  ]
}

then the flow state may be modified in two ways.

If an ActionUnableToRun exception is encountered, then the exception information will be stored in $.FailureInfo. As a result, the flow state will look like this when the HandleError state is executed:

{
  "endpoint_id": "00000000-0000-0000-0000-000000000000",
  "path": "/~/",
  "FailureInfo": {
    "Error": "ActionUnableToRun",
    "Cause": "..."
  }
}

However, if an ActionFailedException is encountered, then the exception information will overwrite the flow state because no ResultPath is specified for that error type. The flow state will look like this when the HandleError state is executed:

{
  "Error": "ActionUnableToRun",
  "Cause": "..."
}