You are currently viewing Azure: Error Handling in API Management

Azure: Error Handling in API Management

In my previous blogs, I have been explaining about the Azure API Management service. Below are the topics covered till now:

We have mostly covered all the topics related to this service. This article is to cover the error handling policies in API Management.

The on-error section

The policy schema has four main sections, inbound, outbound, backend and on-error. The on-error section is like a catch block in try-catch statement in c#. If any error occurs during API management execution, the control falls back to on-error section.

In on-error section, you can modify the error response before sending it back to the API consumer.

    <!-- to be applied to the request go here -->
    <!-- to be applied before the request is forwarded to 
         the backend service go here -->
    <!-- to be applied to the response go here -->
    <!-- to be applied if there is an error condition go here -->

The Last Error Object

In policy expressions, the last error can be access using context.LastError object.

The ProxyError object is exposed through this property. This object provides all the required information which allows publisher to respond to error conditions.

The properties can be used in on-error section for setting the response information.

Last Error Properties

Below properties are available in context.LastError object.


A string value which represents the names of the elements where the error has occurred.


A string value which represents the machine friendly error code. This error code can be used in error handling.

e.g. the reason can be OperationNotFound, SubscriptionKeyNotFound, SubscriptionKeyInvalid, etc.


A string value representing human readable error message.


This is the scope where error has occurred. The value can be “global”, “product”, “api”, “operation”.


A string value. The section where the error has occurred. Possible values are “inbound”, “outbound”, “backend”, “on-error”.


A string value representing the path of policy where the error occurred.

e.g. choose[1]/when[2], etc


A string value representing value of “id” attribute – if specified by the publisher.

Policies Allowed in on-error Section

Following policies can be used in on-error section of policy:

While using above policies, you can use context.LastError object to check which error has occurred. Then based on the type of error, you can customize the message to be sent back to consumer.

I hope you liked this article and this article provided enough information to understand details of Error Handling in API Management service. Please do comment and let me know your thoughts and experiences with API Management.

Leave a Reply