In my previous blogs, I have been explaining about the Azure API Management service. Below are the topics covered till now:
- Introduction to API Management
- How to create API Management instance
- How to publish APIs through API Management instance
- What are policies and how to apply policies in API Management
- Azure: Security in API Management
- Azure: API Management from API Consumer Perspective
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.
<policies>
<inbound>
<!-- to be applied to the request go here -->
</inbound>
<backend>
<!-- to be applied before the request is forwarded to
the backend service go here -->
</backend>
<outbound>
<!-- to be applied to the response go here -->
</outbound>
<on-error>
<!-- to be applied if there is an error condition go here -->
</on-error>
</policies>
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.
Source
A string value which represents the names of the elements where the error has occurred.
Reason
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.
Message
A string value representing human readable error message.
Scope
This is the scope where error has occurred. The value can be “global”, “product”, “api”, “operation”.
Section
A string value. The section where the error has occurred. Possible values are “inbound”, “outbound”, “backend”, “on-error”.
Path
A string value representing the path of policy where the error occurred.
e.g. choose[1]/when[2], etc
PolicyId
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:
- choose
- set-variable
- find-and-replace
- return-response
- set-header
- set-method
- set-status
- send-request
- send-one-way-request
- log-to-eventhub
- json-to-xml
- xml-to-json
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.
Is there a way to raise onerror policy from inbound policy on some custom validation failure.
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.