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.
Note
The on-error
section is not present in policies by default. To add the on-error
section to a policy, browse to the desired policy in the policy editor and add it. For more information about configuring policies, see Policies in API Management.
If there is no on-error
section, callers will receive 400 or 500 HTTP response messages if an error condition occurs.
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.
Name | Type | Description | Required |
---|---|---|---|
Source |
string | Names the element where the error occurred. Could be either policy or a built-in pipeline step name. | Yes |
Reason |
string | Machine-friendly error code, which could be used in error handling. | No |
Message |
string | Human-readable error description. | Yes |
Scope |
string | Name of the scope where the error occurred and could be one of "global", "product", "api", or "operation" | No |
Section |
string | Section name where error occurred. Possible values: "inbound", "backend", "outbound", or "on-error". | No |
Path |
string | Specifies nested policy, for example "choose[3]/when[2]". | No |
PolicyId |
string | Value of the id attribute, if specified by the customer, on the policy where error occurred |
No |
Tip
You can access the status code through context.Response.StatusCode.
Note
All policies have an optional id
attribute that can be added to the root element of the policy. If this attribute is present in a policy when an error condition occurs, the value of the attribute can be retrieved using the context.LastError.PolicyId
property.
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.
Source | Condition | Reason | Message |
---|---|---|---|
configuration | Uri doesn't match to any API or Operation | OperationNotFound | Unable to match incoming request to an operation. |
authorization | Subscription key not supplied | SubscriptionKeyNotFound | Access denied due to missing subscription key. Make sure to include subscription key when making requests to this API. |
authorization | Subscription key value is invalid | SubscriptionKeyInvalid | Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription. |
multiple | Downstream connection (from a client to an API Management gateway) was aborted by the client while request was pending | ClientConnectionFailure | multiple |
multiple | Upstream connection (from an API Management gateway to a backend service) was not established or was aborted by the backend | BackendConnectionFailure | multiple |
multiple | Runtime exception had occurred during evaluation of a particular expression | ExpressionValueEvaluationFailure | multiple |
Predefined errors for policies
The following errors are predefined for error conditions that can occur during policy evaluation.
Source | Condition | Reason | Message |
---|---|---|---|
rate-limit | Rate limit exceeded | RateLimitExceeded | Rate limit is exceeded |
quota | Quota exceeded | QuotaExceeded | Out of call volume quota. Quota will be replenished in xx:xx:xx. -or- Out of bandwidth quota. Quota will be replenished in xx:xx:xx. |
jsonp | Callback parameter value is invalid (contains wrong characters) | CallbackParameterInvalid | Value of callback parameter {callback-parameter-name} is not a valid JavaScript identifier. |
ip-filter | Failed to parse caller IP from request | FailedToParseCallerIP | Failed to establish IP address for the caller. Access denied. |
ip-filter | Caller IP is not in allowed list | CallerIpNotAllowed | Caller IP address {ip-address} is not allowed. Access denied. |
ip-filter | Caller IP is in blocked list | CallerIpBlocked | Caller IP address is blocked. Access denied. |
check-header | Required header not presented or value is missing | HeaderNotFound | Header {header-name} was not found in the request. Access denied. |
check-header | Required header not presented or value is missing | HeaderValueNotAllowed | Header {header-name} value of {header-value} is not allowed. Access denied. |
validate-jwt | Jwt token is missing in request | TokenNotPresent | JWT not present. |
validate-jwt | Signature validation failed | TokenSignatureInvalid | <message from jwt library>. Access denied. |
validate-jwt | Invalid audience | TokenAudienceNotAllowed | <message from jwt library>. Access denied. |
validate-jwt | Invalid issuer | TokenIssuerNotAllowed | <message from jwt library>. Access denied. |
validate-jwt | Token expired | TokenExpired | <message from jwt library>. Access denied. |
validate-jwt | Signature key was not resolved by ID | TokenSignatureKeyNotFound | <message from jwt library>. Access denied. |
validate-jwt | Required claims are missing from token | TokenClaimNotFound | JWT token is missing the following claims: <c1>, <c2>, … Access denied. |
validate-jwt | Claim values mismatch | TokenClaimValueNotAllowed | Claim {claim-name} value of {claim-value} is not allowed. Access denied. |
validate-jwt | Other validation failures | JwtInvalid | <message from jwt library> |
forward-request or send-request | HTTP response status code and headers were not received from the backend within the configured timeout | Timeout | multiple |
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
Feedback
https://aka.ms/ContentUserFeedback.
Kommer snart: I hele 2024 udfaser vi GitHub-problemer som feedbackmekanisme for indhold og erstatter det med et nyt feedbacksystem. Du kan få flere oplysninger under:Indsend og få vist feedback om