Response handler configuration

Configure the Response Handler for Generic OAuth2 and Callout Authenticator API rules.

The Generic OAuth2 rule and Callout Authenticator rule contain a Response Handler field where you can specify how to handle the response. You can use anything in the response received from the callout.

Default Expression

The Response Handler field doesn't display the default expression. When you configure the expression, you can copy and paste this expression in the empty field:

match response
{
{ statusCode: 200..<300, entity }  => Result.ok(entity),
{ statusCode: 401|404 }  => Result.ignore(),
{ status }  => Result.err(status),
_  => Result.err('Invalid response: ' + response.toString())
}

Configuration

Inside of this Response Handler field are two expression objects available:

  • The "response" object, which contains the response from the callout to your URL.
  • The "Result" object, which contains functions to control how you want the response to be handled.

You can modify the default Response Handler expression according to your own response handling logic, using the functions inside the Result object defined in the following table:

Result functions Description 
{
ok: entity => { variant: 'OK', value: entity }


continue: entity => { variant: 'CONTINUE', value:    entity }




ignore: () => { variant: 'IGNORE' },


err: reason => { variant: 'ERROR', reason: reason }
}
 You call the OK function when you want the response to be accepted.
You call the Continue function to perform multiple callouts on a single request in sequence using the response of the first call out in a subsequent callout for further validation.
You call the Ignore function when you want the response to be ignored.
You call the Error function when you want the response to result in an error.

The Continue function doesn't accept the request (differentiating it from the OK function); rather, it just saves the value in the target path for further callouts.

Troubleshooting

The response handler enables you to specify why a request failed. In certain scenarios when the client makes the HTTP call to the authorization/authentication server, you might see in the returned response that the error response handler returned the correct error in the “Failure” field of the response body, but that the server response is a 500 HTTP error.

This combination of errors is possible when the rule executes correctly, but the response from the authentication endpoints results in an error that is not a 401/403 HTTP status code. If the authorization endpoint returns a 401/403 HTTP status code, then the rule ignores the 401/403 HTTP status code and moves on to the next rule to try and authorize the request.

For example, an Org admin sets up the Callout Authenticator rule rule to authenticate APIs based on a bearer token. In this rule, the following expression is configured for the Response Handler field:

Match response
{
  {  statuCode: 200..<300, entity } => Result.continue(entity),
  {  statusCode:400|401|404  }  => Result.err(“bad request from testuser”),
  {  status  }  => Result.err(status),
  _ => Result.err(‘Invalid response: ‘ + response.toString() )
}

However, when the Org admin tests an API, the response to the call displays a 500 HTTP error in the header of the test API call. The 500 HTTP error is the correct message that the client should see in the header of the returned response because the API call was never completed. The root cause might be due to a misconfigured rule downstream, a networking issue, or even mistyped user input.