Fault Handling in Apigee

Hi all,

In my previous blogs on APIGEE we:

1. Went through the basic introduction of Apigee.
2. Went through the main policies and how to apply them on our proxies.
3. Saw how to extract out a header, extract a list of values out of a header.

If you like you can go through those once again here:

1. Basics of Apigee. click here
2. Playing with Policies. click here
3. Extract the content of the header. click here

In this blog, we will dive into the concept of Fault-Handling through Apigee.

Prerequisites:

1. Knowledge of basics of Apigee. 
2. Knowledge of creating a proxy over Apigee. 
3. Knowledge of applying policies in Apigee. 
4. Assign Message Policy Overview.

As you all know that Apigee acts as a gateway between your App-Client and the backend, all the requests are made by the client to the Apigee proxies and then they are mapped back to the backend source. All is well till now, but just for 1 second, think if something broke at your backend or if the connection to the backend is lost or you passed some unprocessable entity with your request to the backend? In such scenarios, the response coming from the backend may not be in a well-managed form and might not be very informative to a person who’s going to debug the issue later.

To manage such scenarios Apigee provides us with a Fault-Handling capability so that we can pass on our custom messages to the client that will also help the developer/debugger to debug into the issue promptly and effectively.

If we don’t provide any fault handling mechanism at Apigee level, we will get a default fault response from APIGEE whenever an unwanted situation like one of those mentioned above arise. For example, let’s try to hit my API proxy with an invalid AppKey(what’s an AppKey?), we will see the default fault response sent by Apigee here:

By Default Apigee responds back with a fault object containing a fault string and an error code section where the fault string would contain a message that would in a way try to give you an overview of why you are seeing a fault and then the error code would represent the Error flow that got hit with your wrong/bad request at Apigee. This, as you can see, is not very much informative, to make it more appealing and informative we use fault handling in Apigee.

Let’s first see how an informative and appealing Fault response is represented at Apigee, in the screenshot below you can see how I made the Apigee fault response more specific when I again hit the proxy endpoint with the wrong AppKey value:

Compare this screenshot with the previous one, this is the minimal change that I have made to make the fault response more informative, you can add more information as per your organization need. On comparing the two, you can see that in the second screenshot I have:

1. Set my Custom Status as 401 Unprocessable Entity(422 is the actual code for that :P but the aim here is to know that we can set it as per our organization business rules) which was previously 401 Unauthorised.
2. The response body now doesn’t contain any default fault string or error code object but it now contains a totally different JSON body defining the Error, HttpMethod Error Code, and the ErrorTitle as well. You can add more fields to this we will see how to do that later in the blog :-) .

By now you might be getting curious, how did I change that Messaging in the response? So let me answer that for you.

1. So the first thing you would need when creating a custom Fault handler in Apigee is an AssignMessage policy that would be responsible for creating your payload containing the custom JSON body in which you can pass all the valuable information for the developer or debugger who would be debugging into the issue later on.
2. You must come up with a particular condition as well because you would want to return a particular fault message only when a particular type of error has occurred, and not for every other fault that might occur during the flow. So deciding a condition is the second big thing.
3. Once you have taken care of the above two steps you would need to add a FaultRules section in your proxy endpoint. A FaultRules section is the place where your flow would reach immediately if in case there occurs some error during the request/response transfer.

Here’s the link for the XML configuration of my AssignMessage policy that I have used here to create my custom informative JSON payload, you can go through the contents here:

AssignMessageForFaultHandling

And here is the link to the proxy endpoint on which I have applied my fault handling

ProxyEndpointForFaultHandling

Please try to implement this at your Apigee-edge accounts and if you face any problem you can always reach out to me or comment your problem in the comments section below.

For your convenience, I have setup my proxy bundle here

FaultRulesHandlingApigee

you can always download it and use it in your accounts but I would like you to give it a try by yourself first and take my bundle as a reference if required. :-)

I’ll be back with details on other exciting features from Apigee in my next blog, stay tuned for richer API management content.

Happy Blogging and Happy reading. :-)