Flow states retry and error handling

States can encounter runtime errors for various reasons:

• Transient errors, such as network outages and congestion
• JSON path resolution errors

By default, when a state encounters a runtime error, the entire ZIS flow fails.

Action and Map states support error handling using a Catch block. You can use a Catch block to avoid failing the entire ZIS flow when a state encounters an error. See Using a Catch block.

In certain situations, ZIS also attempts to retry failed flows. See ZIS flow retry logic.

Using a Catch block

A Catch block specifies a fallback state to run if an Action or Map state encounters a runtime error. Example:

"Zendesk.GetTickets": {
  "Type": "Action",
  "ActionName": "zis:INTEGRATION:action:zendesk.get_tickets",
  "Catch": [
    {
      "ErrorEquals": ["States.ALL"],
      "Next": "AnotherState"
    }
  ],
  "Next": "NextState"
}

Supported properties for a Catch block

Objects in the Catch array support the following properties.

Name	Type	Mandatory	Description
ErrorEquals	array of strings	true	Array of error names. Only valid value is "States.ALL", which matches all error names
Next	string	true	Fallback state to run if the Action or Map state encounters a runtime error and can't retry
ResultPath	string	false	Reference path used to the store the state's output. Later states of the ZIS flow can access the output at this path. Defaults to "$", which replaces the state's input with its output

Catching error response codes

If a custom action's HTTP request receives a non-2xx HTTP response status code, its Action state returns a runtime error. The state also passes the following error message to the $.Cause reference path:

external action failed due to status code: {http_status_code}

For example, if a custom action's request receives a 404 HTTP status code, the $.Cause path contains the following message:

external action failed due to status code: 404

You can use a Catch block and Choice state to conditionally run different flow states based on the $.Cause path's message. For an example, see Manually retrying a ZIS flow.

ZIS flow retry logic

A running ZIS flow will retry if it:

• Fails due to a rate limit error
• Fails due to a server error

During a retry, the entire flow will run again from the beginning. Ensure your use case and flow logic accounts for this. The interval between retries varies based on the retry scenario. Regardless, ZIS will only attempt to run a flow four times: the initial attempt and up to three retry attempts.

If a flow ends on a Fail state, ZIS will not retry the flow.

Retrying a ZIS flow after rate limiting

A 429 HTTP status code means "too many requests." When an API returns an error with this code, it means an account is sending too many requests to the API too quickly. This is called rate limiting.

Some APIs include a Retry-After header in responses with a 429 error. This header specifies how long you should wait before retrying the API call. The header may provide this interval as a number of seconds to wait or a date and time after which you can retry the call.

If an HTTP-based action in a flow receives a 429 error response and the flow fails, the flow will retry based on the Retry-After interval.

Retry-After interval	Flow retry behavior
Less than 120 seconds	Retry after the Retry-After interval
120 seconds or greater	Retry after 120 seconds
No Retry-After header	Retry after 30–330 seconds. If the retry fails, attempt a second retry after a further 60–360 seconds. If the second retry fails, attempt a third and final retry after a further 120–420 seconds.

Retrying a ZIS flow after a server error

A 500 HTTP status code means something has gone wrong with the API's web server.

If an HTTP-based action in a flow receives a 500 error and the flow fails, the flow will retry after 30–330 seconds. If the retry fails, ZIS attempts a second retry after a further 60–360 seconds. If the second retry fails, ZIS attempts a third and final retry after a further 120–420 seconds.

Manually retrying a ZIS flow

To manually retry a flow for other types of errors, use a Catch block in an Action state to catch the error. Then use a Choice state to check the $.Cause reference path for a specific error code. Example:

{
  "StartAt": "Zendesk.GetTicket",
  "States": {
    "Zendesk.DoSomething": {
      "Type": "Action",
      "ActionName": "zis:YOUR_INTEGRATION_NAME:action:zendesk.YOUR_ACTION_NAME",
      "Parameters": {
        "ticketId.$": "{{$.input.ticket.id}}"
      },
      "Catch": [
        {
          "Comment": "ZIS only supports catching all error types, i.e. States.ALL",
          "ErrorEquals": ["States.ALL"],
          "Next": "CheckErrorType"
        }
      ],
      "ResultPath": "$.do_something_result",
      "End": true
    },
    "CheckErrorType": {
      "Comment": "Checks whether the error caught is a 404",
      "Type": "Choice",
      "Choices": [
        {
          "Variable": "$.Cause",
          "StringEquals": "external action failed due to status code: 404",
          "Next": "log.errorCaught.404"
        }
      ],
      "Default": "log.errorCaught.other"
    },
    "log.errorCaught.404": {
      "Comment": "Use this branch to handle 404 error",
      "Type": "Succeed",
      "Message": "I caught a 404 error"
    },
    "log.errorCaught.other": {
      "Comment": "Use this branch to handle other errors",
      "Type": "Succeed",
      "Message": "I caught a non-404 error"
    }
  }
}