Set status code

APPLIES TO: All API Management tiers

The set-status policy sets the HTTP status code to the specified value.

Note

Set the policy's elements and child elements in the order provided in the policy statement. Learn more about how to set or edit API Management policies.

Policy statement

<set-status code="HTTP status code" reason="description"/>

Attributes

Attribute	Description	Required	Default
code	Integer. The HTTP status code to return. Policy expressions are allowed.	Yes	N/A
reason	String. A description of the reason for returning the status code. Policy expressions are allowed.	Yes	N/A

Usage

• Policy sections: inbound, outbound, backend, on-error
• Policy scopes: global, workspace, product, API, operation
• Gateways: classic, v2, consumption, self-hosted

Example

This example shows how to return a 401 response if the authorization token is invalid. For more information, see Using external services from the Azure API Management service.

<choose>
  <when condition="@((bool)((IResponse)context.Variables["tokenstate"]).Body.As<JObject>()["active"] == false)">
    <return-response response-variable-name="existing response variable">
      <set-status code="401" reason="Unauthorized" />
      <set-header name="WWW-Authenticate" exists-action="override">
        <value>Bearer error="invalid_token"</value>
      </set-header>
    </return-response>
  </when>
</choose>

Related policies

• Transformation

Related content

For more information about working with policies, see:

• Tutorial: Transform and protect your API
• Policy reference for a full list of policy statements and their settings
• Policy expressions
• Set or edit policies
• Reuse policy configurations
• Policy snippets repo
• Author policies using Microsoft Copilot for Azure