Return response

  • Article

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 a 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>

Next steps

For more information about working with policies, see: