IBM API Connect – Custom validation error handling with the default Validation policy.


IBM API Connect provides a default ‘Validation’ policy. In case you would like to use this policy to validate API definitions (example given: the body of a POST message), it will provide a default error message. In case you want to do something with the error response of the ‘Validate’ policy (example given: map the message to your company’s standard), you can do this following the steps described in this blog.

Production information: IBM API Connect v2018.4.1.X – v5 compatible gateway

Make sure you have an OpenAPI contract with well-defined definitions (the validation policy only works with definition elements)

Working with the ‘Validate’ policy

Default Validate Policy

Source Code



This feature is used to validate the payload which is defined in the API definition itself. In case the request is directly referring to the definition you can configure the validation policy as shown below:-


The Validate policy should find the correct definition. In case the body is being referred to as a Parameter in our contract which refers to a definition, you will have to put a direct reference to the required definition in your policy. See screenshot:

Below an example of the implementation where you point directly to the required definition:

Here is an example of one the policies defined:-

Each resource has a different definition in the body. Therefore, you use a switch to process each resource independently. The validation policy will configure the specific definition for each resource.

There is no need of THROW activity or an extra IF statement to catch possible errors. The validation policy has a ‘TRY’ mechanism and will throw an error in case there is one.

Catch the error

Assembly configuration

  • If you want to process the error, you need to create a catch in your assembly.
  • If you don’t configure a catch, the error will be processed by the default error handling.
  • If you want a specific handling for the validation error which does not match your default error handling, you will have to configure the ‘ValidateError’ catch.
  • If that catch is not configured, your error will be passed on to the ‘policies_default’ catch. See screenshots for a more detailed view:

Next screenshot shows both the ValidateError catch and policies_default with an implementation:-

Process the error

The error context (after a validation error) looks like this:


“name”: “ValidateError”,

“scope”: “2”,

“source”: “2”,

“httpCode”: “422”,

“httpReasonPhrase”: “Invalid”,

“message”: “Validate REST: xa35://tmp/temp_04839:1:[JSV0002] Invalid object: the property ‘first_name’ is missing.”,

“ignorecatch”: “false”,

“policyTitle”: “validate_person”


In the gateway script, follow the next steps:

  1. Store the error context into a variable
    • var exception =‘policy’).getVariable(‘fw/exception’);
  2. Store details of the error into a context variable
    • apim.setvariable(‘ErrorDetail’, exception[“message”]);
  3. Store the Reason into a context variable
    • apim.setvariable(‘ErrorCode’, exception[“httpReasonPhrase”]);
  4. Store the policy title into a context variable
    • apim.setvariable(‘ErrorPolicy’, exception[“policyTitle”]);

Note: You can also use the other elements shown in the JSON above.

Result of the gateway script:

var exception =‘policy’).getVariable(‘fw/exception’);

apim.setvariable(‘ErrorDetail’, exception[“message”]);

apim.setvariable(‘ErrorCode’, exception[“httpReasonPhrase”]);

apim.setvariable(‘ErrorPolicy’, exception[“policyTitle”]);

Default Map policy

The most efficient error handling would be if you would use the same gateway script to map the response. But to make the example more clear, you will use a default mapping policy to do the actual mapping of the error message.

Add a map policy after the gateway script as shown in the previously and complete as shown in the screenshot below:

When completing the mapping, do not forget to tick the checkbox ‘Merge mapping with others in the same array’.

The source code of the ‘ValidateError’ catch will be as following:-


Your header now contains a Google authorized token.

Written by Niki Heyligen, June 2021

IBM Integration Specialists

Enabling Digital Transformations.

Recent news
Let's get in touch...

​ Find us here

Veldkant 33B
2550 Kontich

Pedro de Medinalaan 81
1086XP Amsterdam
The Netherlands

© 2019 Integration Designers - Privacy policy - Part of Cronos Group integr8 consulting