Behavioral Headers

Vikas PuriWritten by Vikas Puri

Introduction The implementation of mocking services plays a vital role in design-specific development. If we are developing any new project or implementing any new functionality by consuming some API’s which are still in a development phase, no consumers (front-end developer or any other) of the API will wait until the API is completely developed; they need some mocking service with some sample responses and error responses so they can start their development (assuming front-end dev in this case).

With mocking services, we can easily check what successful response we are getting, but it is quite difficult to validate the error response messages. Like how a mocking service can return an error message corresponding to 500 lines of status code, as there is no server involved.

Fortunately, we have “Behavioral Headers” for this, which we will discuss in this article.

What Are Behavioral Headers in MuleSoft?

Behavioral headers in MuleSoft enable you to change the behavior of the mocking service. There are some keys and values which you have to pass in the headers to test the expected behavior of mocking service. In this post, we are going to brief some of the Behavioral Headers provided by MuleSoft. If in case, you want to see it in detail, visit the MuleSoft website here.

Without wasting time, let's dive into the basic concepts of Behavioral Headers.

In order to test Behavioral Headers, we need the RAML specification and its Mocking Service URL. So I have created the sample RAML as shown in Figure 1, after publishing makes it public and get the mocking URL which in my case is:

Behavioral Headers

Figure 1 Test of behavioral header

Now in order to hit this, you can use any client; here I have used Postman.

Let us now go through some of the Behavioral headers:

MS2-Status-Code: MS2-Status-Code Behavioral Header will enforce mocking service to return an error response corresponding to a specific HTTP Status code. Suppose you want the mocking service to return an error response corresponding to 500 status code, there is no way to return that, so in order to achieve this, we just need to pass the following attributes in headers:

Key: MS2-Status-Code

Value: 500

This you can see in Figure 2 as below:

Behavioral Headers

Figure 2 An example of the ms2-status-code used to identify an error response

Note: If you pass any other value that is not implemented in the mocking service, it will throw an error message. Like in my case, I have not implemented the 404 error code, so when I pass 404 as a value, then it will throw an error message as shown in Figure 3.

Behavioral Headers

Figure 3 404 as a value is passed since a 404 error code has not been implemented

S2-Delay: Suppose we are consuming API using front-end Angular, and we know that some API endpoints can have a delay while returning a response, and want to handle the front-end side by introducing Asynchronous concepts. How will mocking service return that delay? Well, here comes the role of MS2-Delay behavior headers.

It's very simple—you just need to provide one header with an MS2-Delay with time in milliseconds as shown in Figure 4.

Behavioral Headers

Figure 4 MS2-Delay with time in milliseconds

Note: You can only provide a maximum time delay of 10000 ms.

MS2-Randomize: While writing a mocking service, if we only provide data types and don’t want to provide response examples because of any reason (like shortage of time, etc.), but the consumer wants that response, then just by setting true corresponding to MS2-Randomize will generate random responses.

For example, suppose that an API specification contained the definitions of this type:

Properties files

            id: integer
                name: string

Now passing MS2-Randomize with true value in headers will generate a random response of something like the code below:


  "id": 2317,
  "name": "BIDSQ"


If you have some error in your RAML, but you want to test some other endpoints which are not having errors, you cannot do that until your API doesn’t have any errors, because when you invoke the mocking service it will validate your RAML first. If you want to skip the validation for mocking service, you need to set false corresponding to the MS2-Strict-Model-Validation in the Headers part.


We have learnt about some Behavioral Headers in MuleSoft, which are useful while testing the mocking services like testing the specific error response code, introducing some delays, generating random responses, and skipping the validation of RAML.