Return response

APPLIES TO: All API Management tiers

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.

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

<return-response response-variable-name="existing context variable">
  <set-status>...</set-status>
  <set-header>...</set-header>
  <set-body>...</set-body>
</return-response>

Attributes

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

Elements

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

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.

Example

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

For more information about working with policies, see: