The Integration blog covers the latest in product updates, best practices, customer stories, and more.

A Simple Guide to Return Custom HTTP Error Response from REST based OIC Flows

The REST Adapter in the trigger (inbound) direction exposes an HTTP endpoint that HTTP clients can request for using an HTTP request, and returns an HTTP response.

If successful, the REST Adapter returns a success response. The REST Adapter returns an error response with an HTTP status belonging to the error family of codes depending on the situation. The following table describes the possible cause and the REST Adapter response.



HTTP Status


Invalid client request


There are several conditions that can cause client side failures, including:

  • An invalid resource URL

  • Incorrect query parameters

  • An unsupported method type

  • An unsupported media type

  • Bad data

Downstream processing errors


All other errors that can occur within the integration, including:

  • An invalid target

  • An HTTP error response

  • General processing errors


In addition, there could be several situations where an integration developer wants to return a custom HTTP error response based on the business logic. 

Let’s take one such example and illustrate how this can be done easily within the orchestration flow. 

The REST adapter provides very basic type validation out of the box. Any other validation like schema or semantic validation is turned off as it has a significant performance overhead. 

This post demonstrates how integrations developers can include validation logic and raise a fault with a custom fault code from within the orchestration flow. This fault is returned as an HTTP error response back to the client by the REST Adapter. 

Overview:In our example, we have a REST based trigger that takes a user input. The integration developer checks the user input and raises a fault which is returned as a HTTP response with an error code back to the caller. 

Step 1: Create a REST based trigger that takes a JSON input and a JSON response. 














Step 2: Include a switch statement to validate the input. This step can also be externalized in a separate validation service. This service could also be another integration flow.  


Step 3: If the validation condition is not true, then return an APIInvocationError. As illustrated below, the APIInvocationError is assigned specific values to reflect the validation failure.

For ex: The APIInvocationError/errorCode is set a value of 400. This ensures that the HTTP response is returned with an error code 400 back to the caller. If this is not set, then fault is returned back to the client as an HTTP error response with code 500 by default. (Internal server error) 

The error details section is reserved for the actual cause of the error. Since the integration developer is throwing this error, they can assign any appropriate value.

Let’s review the runtime behavior of our sample integration: 

1. Positive scenario:  The required field is present. The integration completes successfully and returns a HTTP 200 response back to the client. 

2. RequiredID is present but has an empty value: The integration will return an HTTP error response with status code 400 back to the client. 

3. RequiredID is not present: The integration will return an HTTP error response with status code 400 back to the client.


The flow trace depicts that the switch condition for invalid input was executed from where the APIInvocationError was raised, that resulted in the HTTP error response back to the client. 

In summary, using the steps mentioned above, an integration developer can easily send an HTTP error response from within the orchestration logic using a FaultReturn activity. 

Some known limitations:

1. Users can customize the response status but this will not be shown as part of the Swagger contract as runtime overrides are not known as part of the interface. 

2. Http responses status cannot be customized in the following conditions: 

    a. If the request is async one way. In this case the response status will aways be 201. 

    b. Errors during trigger request/response handling will be reported using a pre-defined error codes. 

    c. Basic routing (map my data) doesn't allow fault handling and error response in such scenarios cannot be customized. 

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.