Skip to content
CA API Gateway - 9.3
Documentation powered by DocOps

Customize Error Response Assertion

Last update April 2, 2019

The Customize Error Response assertion lets you configure the error response for a service. You can select the following responses when an error is encountered:

  • Template response: Lets you define your own message to be returned. This is the default.
  • Drop connection: When the policy fails, simply drop the connection without providing any response.

For SOAP services, consider using the Customize SOAP Fault Response Assertion as well, as it contains SOAP-specific settings.

Using the Assertion

  1. Do one of the following:
    • To add the assertion to the Policy Development window, see Add an Assertion.
    • To change the configuration of an existing assertion, proceed to step 2 below.
  2. Right-click Customize Error Response in the policy window and select Error Response Properties or double-click the assertion in the policy window. The assertion properties are displayed. 
  3. Configure the error response:

    Setting Description
    Error Level

    Select the response to use for an error:

    • Template Response: The assertion will return the response in the Response Body.
    • Drop Connection: The connection is simply dropped, with no response ("stealth" mode).
    Response HTTP Status Enter the HTTP status code to return. Alternatively, you may enter a context variable that contains the status code.
    Response Content-Type Enter the valid Content-Type header to return. Alternatively, you may enter a context variable that contains the Content-Type.
    Extra Response Headers

    Optionally specify one or more custom HTTP headers to be inserted into the custom error response (for example, to transmit application-specific metadata).

    Be sure you are aware of the consequences of adding headers to a message. If in doubt, please contact your system administrator.


    To add a header:

    1. Click [Add].
    2. Enter the Name and Value of the header. You may reference context variables in both fields.
    3. Click [OK]. The header is added to the list.

    To modify a header:

    1. Select the header to modify and then click [Edit].
    2. Modify the Name or Value as required.
    3. Click [OK].

    To remove a header:

    • Select the header to remove and then click [Remove].
    Response Body

    Enter the text to be returned in the response. This text will be returned as entered; the assertion performs no validation. You may include context variables in the response body to provide additional informational information about the error. The assertion can utilize any context variable set during the execution of the policy.

    Note: The Response Body does not support use of a Document Type Definition (DTD) for XML content.

    Tip: The Response Body can use context variables output from the encapsulated assertion.

    [Include the policy download URL as an HTTP header]

    Select this check box to indicate that the policy download URL is included as an HTTP header in the response if it is required.

    Clear this check box to not include the policy download URL in the HTTP header in a response.

  4. Click [OK]when done.

Was this helpful?

Please log in to post comments.

  1. Guillaume Pujol
    2018-05-18 06:08

    It might be good to document that context variables used in the template error response will be evaluated when the error is triggered, and not when the "Customize Error Response" assertion is evaluated. This means you can actually change the value of context variables after the "Customize Error Response" and those changes will be reflected in the error response, if an error occurs.

    1. Harris
      2019-03-28 05:10

      Thanks for that clarification, that is definitely confusing at first look. It would also be good to document which values would need to be exported from an encapsulated assertion, to allow the parent assertion to passthrough the error context. From my debugging it looks like its error.msg, content, content-type, and status.

      1. Andrea Tejokusumo
        2019-04-02 06:13

        Thank you both for your suggestions. We have amended the documentation accordingly.