Errors within Action Flows
Errors in an Action Flow fall into two types:
- Input errors happen before the Action Flow starts, when the request or event that triggers it can't be processed, such as malformed JSON, a failed authentication, or otherwise invalid input. These prevent the Action Flow from starting.
- Step errors happen once the Action Flow is running when a step fails as it's evaluated. In certain situations, steps within an Action Flow may cause an error, which stops the Action Flow and marks it as failed.
When the Action Flow is marked as a failure, analytic events are emitted which can be used as part of a webhook subscription to notify external systems of the failure.
Handling errors
Error handling within Action Flows is in preview and may be subject to change. Please contact us to have this feature enabled in your organization or to provide feedback.
Before the Action Flow is marked as failed, you can set up an error handler branch that is executed after a step fails. This allows you to perform actions based on the error that caused the failure, such as:
- Notifying internal error monitoring tooling using a Send a request step or a chat message to Slack or Microsoft Teams.
- Using a Branch flow step to perform different actions based on the error output.
- Cancel any cards that have already been sent by using the Action a card step.
- Triggering a dedicated error handler Action Flow using the Atomic.io step, allowing you to consolidate the steps to take for an error across multiple Action Flows in one place.
Adding an error handler
To add an error handler, open your Action Flow in the editor and:
- Select Add error handler next to the Action Flow starts step. An Action Flow fails branch is added alongside the main flow.
- Select the + on the Action Flow fails step to add a step.
- Add and configure as many steps as you need. Details of the error that caused the failure, and the step that failed, are available to these steps as error output variables, shown under Error outputs in the context picker.
The error handler runs as a separate branch after a step in the main flow fails, and before the Action Flow is marked as failed.
Limitations
The error handler doesn't support all step types, such as Wait steps, meaning you can't have any steps after a Send a Card step within the error handler.
If a step within the error handler also fails, the error handler is not re-run and the Action Flow is stopped and marked as a failure.
Triggering an error
Triggering errors using a Stop Action Flow step is in preview and may be subject to change. Please contact us to have this feature enabled in your organization or to provide feedback.
To manually trigger an error and force the Action Flow invocation into a failure state, you can use the Stop the Action Flow step by setting its Outcome to Error.
You might want to force a failure when an upstream service returns an unexpected response, a required piece of data is missing, or a validation check fails, so that the Action Flow runs its error handler and is reported as failed in analytics rather than silently completing.
When this step is executed, the step will produce a failure with a FLOW_STOPPED_WITH_ERROR error code. Within the step, you can optionally provide an error message that will appear within the error handler and the relevant analytic events.
Reference
Error analytic events
| Event name | Description |
|---|---|
action-flow-step-failed | Emitted when a step within the Action Flow has failed. This event contains information about the error causing the failure |
action-flow-error-handler-triggered | Emitted if an error handler is set up and has been triggered by a failing step within the Action Flow |
action-flow-failed | Emitted once the Action Flow has stopped after any error handler steps |
Error codes
Input error codes
These errors happen before the Action Flow starts running, so they can't be caught by an error handler. Instead, they're returned in the response to the request that triggered the Action Flow.
| Error code | Description |
|---|---|
ACCESS_DENIED_TO_ENVIRONMENT | The caller is authenticated but isn't permitted to trigger Action Flows in the target environment |
ACTION_FLOW_EVALUATION_FAILED | The request could not be processed, such as a reused invocation ID |
ARCHIVED_FLOW | The Action Flow being triggered has been archived and can no longer run |
BAD_INPUT | The request contained invalid or missing input, such as a malformed body or reused invocation ID |
CONNECTOR_NOT_FOUND | No connector matched the request, such as an incorrect connector secret or a removed connector |
CONNECTOR_NOT_FOUND_WITH_FLOW_CONFIG_ID | No connector was found for the specified Action Flow |
CONNECTOR_PAUSED | The connector is paused, so only test requests are accepted |
EVENT_SOURCE_NOT_FOUND | The event source named in the request could not be found |
INTERNAL_ERROR | An unexpected error occurred while processing the request. Contact Atomic Support if this happens |
INVALID_AUTH_CONFIG_FOR_CONNECTOR | The request could not be authenticated against the connector's configuration |
INVALID_BODY | The request body could not be read, such as an invalid JWT token or secret |
INVALID_CONNECTOR_AUTH | The request's authentication was missing or invalid, such as a missing or incorrect signature |
INVALID_CONNECTOR_SECRET | The connector secret in the request is missing or invalid |
INVALID_INTEGRATION_AUTH | The integration's authentication configuration is missing or invalid |
INVALID_LIVE_MODE | The request's mode doesn't match the Action Flow, such as a live request to a draft Action Flow |
IP_ADDRESS_NOT_WHITELISTED | The request came from an IP address that isn't on the connector's allow list |
JSON_PARSE_ERROR | The request body is not valid JSON |
PAYLOAD_MAPPING_FAILED | The request payload could not be mapped to the Action Flow's expected input |
VARIABLE_VALIDATION_FAILED | One or more Action Flow variables failed validation against the request |
Step error codes
These are the error codes that can be caught by an error handler. Each is produced by a step failing while the Action Flow is running.
| Error code | Description |
|---|---|
ACTION_FLOW_EVALUATION_FAILED | An error occurred while evaluating a User experiment step. Contact Atomic Support if this happens |
BAD_CONFIGURATION | A step was misconfigured, such as an invalid variable mapping or malformed step properties |
BAD_INPUT | A step received invalid input, such as an out-of-range or unparseable duration or time |
FLOW_STOPPED_WITH_ERROR | The Action Flow was stopped using the Stop the Action Flow step with an Outcome set to Error |
HTTP_REQ_FAILED | A HTTP request failed and did not receive a response code, such as a DNS resolution or certificate issue |
HTTP_REQ_FAILED_4xx | A HTTP request responded with a 4XX response code |
HTTP_REQ_FAILED_5xx | A HTTP request responded with a 5XX response code |
HTTP_REQ_FAILED_OTHER | A HTTP request failed with an unknown response code, such as a timeout |
INTERNAL_ERROR | An unexpected error occurred while evaluating a step, or a failing step reported no more specific code. Contact Atomic Support if this happens |
SCRIPT_EVALUATION_FAILED | An error was triggered within the script being run as part of a Run a script step |