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.
In certain situations, ZIS also attempts to retry failed flows. See ZIS flow retry logic.
Catch block specifies a fallback state to run if an Action or Map state
encounters a runtime error. Example:
Objects in the
Catch array support the following properties.
|ErrorEquals||array of strings||true||Array of error names. Only valid value is "States.ALL", which matches all error names|
|Next||number||true||Fallback state to run if the Action or Map state encounters a runtime error and can't retry|
|ResultPath||number||false||JSON 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|
A running ZIS flow will retry if it:
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.
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
||Flow retry behavior|
|Less than 120 seconds||Retry after the
|120 seconds or greater||Retry after 120 seconds|
||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.|
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.
To manually retry a flow for other types of errors, use a
Catch block in an Action state to catch the error, followed by a Choice state to check for a specific error code. Example:
"Comment": "ZIS only supports catching all error types, i.e. States.ALL",
"Comment": "Checks whether the error caught is a 404",
"StringEquals": "external action failed due to status code: 404",
"Comment": "Use this branch to handle 404 error",
"Message": "I caught a 404 error"
"Comment": "Use this branch to handle other errors",
"Message": "I caught a non-404 error"