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 ReplyCancel reply

This Post Has 2 Comments

  1. venki

    Is there a way to raise onerror policy from inbound policy on some custom validation failure.

    1. Manoj Choudhari
      Manoj Choudhari

      APIM has 4 sections where policies can be specified – inbound, backend, outbound and on-error. The policies are executed in this sequence and in the order in which they are configured. If any error occurs in INBOUND policy, then backend and outbound sections are automatically skipped and on-error section is raised. So, one of the approach for you may be:
      – In on-error section, you can use context.LastError property to figure out where the error occurred.
      – context.LastError.Section should give you name of the section (inbound, backend or outbound) where the error occurred.
      – context.LastError.Reason should give you the machine friendly error code
      – context.LastError.Message should give you human readable error description.

      I hope this answers your question.