PingAuthorize

Sideband error templates

REST API clients often expect a custom error format that the API produces. Some clients might fail unexpectedly if they encounter an error response that uses an unexpected format.

When PingAuthorize Server proxies a REST API, it forwards errors that the API returns to the client as they are, unless a policy dictates modifications to the response. In the following scenarios, PingAuthorize Server returns an error that the Sideband API generates:

  • The policy evaluation results in a deny response. This typically results in a 403 error.

  • An internal error occurs in the Sideband API. This typically results in a 500 error.

By default, these responses use a simple error format, as shown in the following example:

{
  "errorMessage": "Access Denied",
  "status": 403
}

The following table describes the default error format.

Field Type Description

errorMessage

String

Error message

status

Number

HTTP status code

Because some REST API clients expect a specific error-response format, PingAuthorize Server provides error templates to respond with custom errors. Error templates, which are written in Velocity Template Language, define the manner in which a Sideband API Endpoint produces error responses.

The following table identifies the context parameters that are provided with error templates.

Parameter Type Description

status

Integer

HTTP status

message

String

Exception message

Example: Configure error templates

This example demonstrates the configuration of a custom error template for a Sideband API Endpoint called Test API.

The following fields are associated with the error responses that use this error template:

  • code

  • message

To create the error template, perform the following steps:

  1. Create a file named error-template.vtl with the following contents:

    #set ($code = "UNEXPECTED_ERROR")
#if($status == 403)
  #set ($code = "ACCESS_FAILED")
#end
{
  "code":"$code",
  "message":"$message"
}

  2. Add the error template to the configuration.

    dsconfig create-error-template \
  --template-name "Custom Error Template" \
  --set "velocity-template<error-template.vtl"

  3. Assign the error template to the Sideband API Endpoint.

    dsconfig set-sideband-api-endpoint-prop \
  --endpoint-name "Test API" \
  --set "error-template:Custom Error Template"

The error template is used whenever the Sideband API generates an error in response to a request.