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.