Error handling

ACE supports several ways of returning errors from an API endpoint

• Error response from flow
• Global error handler
• API handlers

Default error response

If ACE flows contain unhandled errors, default response is HTTP status code 500 and message with error details.

For example, if flow flowWithError.yaml contains an error, then API response is following:

{
  "statusCode": 500,
  "message": "Error in flow 'flowWithError.yaml': Jsonata Step: missing 'config.targetPath' property"
}

Error response from flow

It is possible to set custom response body, status code and headers using Response Step in the flow error handling logic.

Legacy way to set custom error response is to set result property in the flow with following structure:

{
  "errorHandler": true,
  "errorResponse": {
    "statusCode": 400,
    "response": {"message": "Bad request"}
  }
}

response property can be string or object.

In the example above API with error would respond with body {"message": "Bad request"} and HTTP code would be 400.

API handlers

API handlers offer the ability to attach custom flows to API in a cross-cutting way by specifying a request URL regex pattern. It's possible to add flows on error event and use custom logic to handle the error and return custom response like in regular flow. See API error handlers for more details.

Example

This example shows simple error handling using API error handlers.

Example has:

• flows sampleFlow and customResponse
• handler which listens for error event
• API

sampleFlow throws error during API execution and the attached handler handles the error and sets custom error response. As a result API execution gives the custom error response as result.

Flows

customResponse

tags: []
sampleInputSchema: ""
sampleData: {}
description: ""
steps:
  - name: Step response
    description: Return custom response
    config:
      continueFlowExecution: false
      stopAPIExecution: false
      responseTypeFile: false
      body:
        message: Unexpected error
        details: "{{errors[0].error}}"
      statusCode: "500"
    stepType: response

sampleFlow

tags: []
sampleInputSchema: ""
sampleData: {}
description: ""
steps:
  - name: Step jsonata
    description: ""
    config:
      maps:
        - {}
    stepType: jsonata

Error handler definition

API definition

errorHandlerExample-get

path: /errorHandlerExample
method: get
flow: sampleFlow.yaml
secured: false
definition:
  operationId: sampleFlow
  responses: {}
  parameters: []

Result

On execution API returns response with status code 500 (coming from API error handler) and body:

{
  "message": "Unexpected error",
  "details": "Error in flow 'sampleFlow': Jsonata Step: missing 'config.jsonata' property containing the jsonata string transformation"
}

Global Error Handling

Global error handlers allow to change default error response for all APIs.

Global error handlers are triggered if flow has unhandled error and doesn't have explicitly defined flow error response.

If error response message is matched by Error Pattern then response status code is set to Error Code and response message is set to Error Message.

Global error handlers can be defined in Error Handlers section and have the following properties:

• Name - error handler name
• Error Pattern - regex to match the error message in default response. You can use . regex to match all errors.
• Error Code - HTTP status to return, this code is also set in response statusCode field.
• Error Message - text to set in response message field