PingAuthorize

Gateway error templates

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

When a REST API is proxied by PingAuthorize Server, errors that the REST API returns are forwarded to the client as is, unless a policy dictates a modification of the response. In the following scenarios, PingAuthorize Server returns a gateway-generated error:

  • When the policy evaluation results in a deny response. This scenario typically results in a 403 error.

  • When an internal error occurs in the gateway, or when the gateway cannot contact the REST API service. This scenario typically results in a 500, 502, or 504 error.

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

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

The following table describes this 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 a facility for responding with custom errors, called error templates. An error template is written in Velocity Template Language and defines the manner in which a Gateway API Endpoint produces error responses.

Error templates feature the following context parameters.

Parameter Type Description

status

Integer

HTTP status

message

String

Exception message

requestURI

String

Original Request URI

requestQueryParams

Object

Query parameters as JSON object

headers

Object

Request headers as JSON object

correlationID

String

Request correlation ID

For more information, see Sideband error templates.

Configuring error templates example

The example in this section demonstrates the configuration of a custom error template for a Gateway API Endpoint named Test API.

About this task

Error responses that use this error template feature the following fields:

  • code

  • message

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, as follows:

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

  3. Assign the error template to the Gateway API Endpoint, as follows:

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

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

    Example:

    A policy deny results in a response like the following example:

    HTTP/1.1 403 Forbidden
Content-Length: 57
Content-Type: application/json;charset=utf-8
Correlation-Id: e7c8fb82-f43e-4678-b7ff-ae8252411513
Date: Wed, 27 Feb 2019 05:54:50 GMT
Request-Id: 56

{
  "code": "ACCESS_FAILED",
  "message": "Access Denied"
}