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.

Specific runtime errors in specific states can also trigger a retry of a failed ZIS flow. 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

The following table contains the states and runtime errors that trigger a retry of a failed ZIS flow. The interval between retries varies based on the state and error.

State	Runtime error	Interval between retries
Action	429 rate limit error	See Retrying a ZIS flow after rate limiting
Action	5xx server error	See Retrying a ZIS flow after a server error
Action	Any error other than the following: 429 rate limit error 5xx server error Action parse error Connection missing error Action invalid domain error Action invalid request	Retry runs immediately
Choice	Any	Retry runs immediately
Map	A child state encounters a runtime error that triggers a flow retry	Uses the retry interval for the child state and error
Pass	Any	Retry runs immediately
Wait	Any	Retry runs immediately

A Fail state won't trigger a retry of a ZIS flow, even if it encounters a runtime error.

ZIS only attempts to run a flow up to four times: the initial attempt and up to three retry attempts. During a retry, the entire flow runs again from the beginning. Ensure your use case and flow logic account for this.

Retrying a ZIS flow after rate limiting

A 429 HTTP status code means "too many requests." When a web server returns an error with this code, it means rate limiting has kicked in because the client is sending too many requests too quickly.

Some servers include a Retry-After header in responses with a 429 error. This header specifies how long you should wait before retrying the request. 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.

A custom action in an Action state can send an HTTP request. If a custom action's HTTP request receives a 429 HTTP response status code 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 5xx HTTP status code means something has gone wrong with the responding web server.

A custom action in an Action state can send an HTTP request. If a custom action's HTTP request receives a 5xx HTTP response status code 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"
    }
  }
}

Flow circuit breaker

If a flow has more than 5,000 events occur within a 15-minute period, a circuit breaker will be triggered if either of the following limits are reached:

• More than 50% of those events lead to flows failing with a retryable error
• More than 20,000 retryable errors occur within that period

If triggered, the circuit breaker will drop subsequent events for 30 seconds.

After 30 seconds, ZIS will process the next event for the flow. If successful, the error thresholds will be reset. If not, ZIS will wait another 30 seconds before repeating the cycle until such time that the flow succeeds.