Error handling in API Management policies

APPLIES TO: All API Management tiers

By providing a ProxyError object, Azure API Management allows publishers to respond to error conditions, which may occur during processing of requests. The ProxyError object is accessed through the context.LastError property and can be used by policies in the on-error policy section. This article provides a reference for the error handling capabilities in Azure API Management.

Error handling in API Management

Policies in Azure API Management are divided into inbound, backend, outbound, and on-error sections as shown in the following example.

<policies>
    <inbound>
        <!-- statements to be applied to the request go here -->
    </inbound>
    <backend>
        <!-- statements to be applied before the request is
             forwarded to the backend service go here -->
    </backend>
    <outbound>
        <!-- statements to be applied to the response go here -->
    </outbound>
    <on-error>
        <!-- statements to be applied if there is an error
             condition go here -->
    </on-error>
</policies>

During the processing of a request, built-in steps are executed along with any policies, which are in scope for the request. If an error occurs, processing immediately jumps to the on-error policy section. The on-error policy section can be used at any scope. API publishers can configure custom behavior such as logging the error to event hubs or creating a new response to return to the caller.

Policies allowed in on-error

The following policies can be used in the on-error policy section.

• 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
• limit-concurrency
• mock-response
• retry
• trace

LastError

When an error occurs and control jumps to the on-error policy section, the error is stored in context.LastError property, which can be accessed by policies in the on-error section. LastError has the following properties.

Predefined errors for built-in steps

The following errors are predefined for error conditions that can occur during the evaluation of built-in processing steps.

Predefined errors for policies

The following errors are predefined for error conditions that can occur during policy evaluation.

Example

Setting an API policy to:

<policies>
    <inbound>
        <base />
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <set-header name="ErrorSource" exists-action="override">
            <value>@(context.LastError.Source)</value>
        </set-header>
        <set-header name="ErrorReason" exists-action="override">
            <value>@(context.LastError.Reason)</value>
        </set-header>
        <set-header name="ErrorMessage" exists-action="override">
            <value>@(context.LastError.Message)</value>
        </set-header>
        <set-header name="ErrorScope" exists-action="override">
            <value>@(context.LastError.Scope)</value>
        </set-header>
        <set-header name="ErrorSection" exists-action="override">
            <value>@(context.LastError.Section)</value>
        </set-header>
        <set-header name="ErrorPath" exists-action="override">
            <value>@(context.LastError.Path)</value>
        </set-header>
        <set-header name="ErrorPolicyId" exists-action="override">
            <value>@(context.LastError.PolicyId)</value>
        </set-header>
        <set-header name="ErrorStatusCode" exists-action="override">
            <value>@(context.Response.StatusCode.ToString())</value>
        </set-header>
        <base />
    </on-error>
</policies>

and sending an unauthorized request will result in the following response:

Next steps

For more information working with policies, see:

• Policies in API Management
• Transform APIs
• Policy Reference for a full list of policy statements and their settings
• Policy samples