Return response

The return-response policy cancels pipeline execution and returns either a default or custom response to the caller. Default response is 200 OK with no body. Custom response can be specified via a context variable or policy statements. When both are provided, the response contained within the context variable is modified by the policy statements before being returned to the caller.


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

<return-response response-variable-name="existing context variable">


Attribute Description Required Default
response-variable-name The name of the context variable referenced from, for example, an upstream send-request policy and containing a Response object. Policy expressions aren't allowed. No N/A


Element Description Required
set-status Sets the status code of the response. No
set-header Sets a header in the response. No
set-body Sets the body in the response. No


Usage notes

  • A liquid template doesn't work when specified inside the body (set using set-body) of the return-response policy. The return-response policy cancels the current execution pipeline and removes the request body and response body in the current context. As a result, a liquid template specified inside the policy receives an empty string as its input and won't produce the expected output.


   <set-status code="401" reason="Unauthorized"/>
   <set-header name="WWW-Authenticate" exists-action="override">
      <value>Bearer error="invalid_token"</value>

Next steps

For more information about working with policies, see: