PingOne Platform APIs

Error codes

This topic describes common PingOne top-level and detail API error messages that you might encounter when an error occurs. An error response consists of a high-level error code that must be handled by the client and optional details containing specific information on how to resolve the fault.

Specific error codes within an error code class (such as, all 4xx error codes) are subject to change. Ensure that your client applications adapt to such changes. For example, a request that previously returned an error code of 400 Bad Request, might now return an error code of 403 Forbidden.

The PingOne API errors return a response payload formatted as follows:

Property Description

id

A unique identifier that is stored in log files and always included in an error response. This value can be used to track the error received by the client, with server-side activity included for troubleshooting purposes.

code

A general fault code which the client must handle to provide all exception handling routines and to localize messages for users. This code is common across all PingOne services and is human readable (such as a defined constant rather than a number). Refer to Top-level error messages for the possible codes here.

message

A short description of the error. This message is intended to assist with debugging and is returned in English only.

target

The item that caused the error (such as a form field ID or an attribute inside a JSON object).

details

Additional details about the error to help resolve the error.

details.code

A general fault code identifying further information. Refer to Detail-level error messages for the possible codes here.

details.innererror

Additional details to help the client developer resolve the fault (primarily for UI validation reasons). These attributes can be used:

* rangeMinimumValue. Errors that failed due to range violation. This attribute represents the minimum value of the range.

* rangeMaximumValue. The maximum range or value of an attribute.

* allowedPattern. A regex pattern describing an acceptable input pattern.

* allowedValues. A list describing acceptable values.

* maximumValue. The maximum value allowed for the request.

details.message

Additional information about the error.

details.target

Additional information about the item causing the error.

A top-level error message looks like this:

HTTP/1.1 400 BAD REQUEST
{
  "id" : "6c796712-0f16-4062-815a-e0a92f4a2143",
  "code" : "INVALID_DATA",
  "message" : "The request could not be completed. One or more validation errors were in the request."
}

A detail-level error message provides more information about the error. Specific codes at the detail level can be introduced by each service to reflect the actions in that service. A detail-level error message looks like this:

HTTP/1.1 400 BAD REQUEST
{
  "id" : "6c796712-0f16-4062-815a-e0a92f4a2143",
  "code" : "INVALID_DATA",
  "message" : "The request could not be completed. One or more validation errors were in the request.",
  "details" : [
  {
    "code" : "REQUIRED_VALUE",
    "target" : "username",
    "message" : "Username is required and cannot be empty."
  },
  {
    "code" : "INVALID_VALUE",
    "target" : "employeeType",
    "message" : "Invalid value for employee type."
    "innerError" : {
      "allowedValues" : [ "EMPLOYEE", "CONTRACTOR" ]
    }
  }
}

For endpoints that return binary data, it is recommended that clients use the Accept request header to specify that the client can also receive an application/json response (for example, Accept: application/x-x509-ca-cert, application/json). This addition to the Accept header prevents 404 NOT_FOUND errors that can be returned by the API gateway as 500 UNEXPECTED_ERROR messages.

Top-level error messages

The following table lists the top-level error messages, the response code, and common conditions that caused the error to occur.

Code Response code Conditions Default message Examples

INVALID _DATA

400

Valid request structure received.
One or more data validation errors.
Each validation error should be described in a details object.

The request could not be completed. One or more validation errors were in the request.

Create or update request with an attribute with an invalid data type.
Data failed validation rules.
Invalid value supplied for an enum.

INVALID_REQUEST

400, 405

Invalid request received.
Malformed JSON, malformed HTTP request.

The request could not be completed. The request was malformed or invalid.

The JSON structure was incorrectly formatted.
A POST request was submitted without a required body.
Incorrect Accept or Content-Type.
Method not allowed on an endpoint (for example, POST to a URL that does not support POST).

REQUEST_FAILED

400

Valid request structure received.
Error occurred during processing of the request (not strictly validation).
Each processing error should be described in a details object.

The request could not be completed. There was an issue processing the request.

A password check action failed.

NOT_FOUND

404

URL specified is not found

The request could not be completed. The requested resource was not found.

Accessed a resource that does not exist.
Accessed a resource that has been hidden from the user (licensing, multi-tenancy concerns).

ACCESS_FAILED

401, 403

Request failed due to authorization issue.

The request could not be completed. You do not have access to this resource.

Attempted a request with and expired, invalid or missing token.
Attempted a request where the token did not have permissions.
Attempted a request where the token is not licensed to request, or the license was exceeded.

REQUEST_LIMITED

429

Request was rate-limited

The request could not be completed. The current rate limiting conditions are shown in the following:
RateLimit-Limit: The requests quota in the time window.
RateLimit-Remaining: The remaining requests quota in the current window.
RateLimit-Reset: The time remaining in the current window, specified in seconds.

User is over quota for the request. See Rate Limiting for more information.

UNEXPECTED_ERROR

500

Uncaught error occurred
Platform outage (502, 503, 500)

There was an unexpected error with the service. Please try again later.

Identifies an internal problem such as a database connectivity issue.

Detail-level error messages

The following table lists the detail-level error messages, the response code, and common conditions that may cause the error to occur.

Code Response code Top-level match Conditions Default message Examples

CONSTRAINT_VIOLATION

400

REQUEST_FAILED

A request violated a service constraint.

A request violates a constraint imposed by the service.

An attempt to delete a Population having Users.

EMPTY_VALUE

400

INVALID_DATA

INVALID_DATA top level error.
Request attempted to clear an optional value (needs to be explicitly set to null).
Nulling or clearing a required value would result in a REQUIRED_VALUE error.

The value cannot be empty.

Attempted to update a value to an empty string.

INSUFFICIENT_PERMISSIONS

403

ACCESS_FAILED

The actor doesn’t have the sufficient permissions to make the request.

You do not have permissions, or are not licensed to make this request.

Either the user or the token has insufficient permissions to make the request.

INVALID_FILTER

400

REQUEST_FAILED

REQUEST_FAILED top level error.
Request contains a filter.
Syntax errors in that filter expression.
Unsupported operators included in filter expression.

The specified filter was invalid.
The filter attribute was invalid or does not support filtering.
The value provided is invalid.

Filter attribute is not filterable.
Filter operator was invalid or not supported.
Filter value was invalid or of a wrong type.

INVALID_OTP

400

INVALID_DATA

INVALID_DATA top level error.
Request contains an invalid OTP.

Wrong OTP was provided.

An incorrect OTP was submitted at sign on.

INVALID_PARAMETER

400

REQUEST_FAILED

REQUEST_FAILED top level error.
Request contains a known query string parameter.
That parameter contains a value that can’t be processed.

A query string parameter or value is not valid for this request.

Invalid cursor supplied using the "cursor" parameter.

INVALID_TOKEN

401

ACCESS_FAILED

A request contained an invalid token, authorization header, or both.

The authorization token is either missing, invalid, or expired.

A token wasn’t present in the request.
The Authorization header was missing.
The token presented failed a signature check.
The token presented contained invalid claims.
The token isn’t a Java Web Token (JWT).

INVALID_VALUE

400

INVALID_DATA

INVALID_DATA top level error.

One or more issues were found in the request data.
The attribute is immutable and can not be updated.
Invalid value for attribute.

Age must be a number.
Region must be NA, CA, EU, AU, SG, or AP.
Email must be in email format.

LICENSE_EXCEEDED

403

ACCESS_FAILED

A licensing enforcement limit was reached.

The request exceeded your license limit.

Licensed for five environments, has five existing environments, an attempts to create another environment.

LIMIT_EXCEEDED

429

REQUEST_LIMITED

A rate limit was reached.

The request exceeded the allowed rate limit.

Too many request too quickly.

OUT_OF_RANGE

400

INVALID_DATA

INVALID_DATA top level error.
Value for attribute is out of a defined range.

The request contains an attribute value that is outside the specified range.

Age must be between 1 and 150
Password length is too short.

QUOTA_EXCEEDED

429

REQUEST_LIMITED

A user, licensing or billing quota was exceeded.

The request will exceed your quota.

Daily SMS/Voice limit was exceeded.

REQUIRED_VALUE

400

INVALID_DATA

INVALID_DATA top level error.
Request is missing a required attribute.

The request is missing a required value.

Username attribute is required to create a user.
Region is required to create an environment.
Attempted to update an environment and remove region.

SIZE_LIMIT_EXCEEDED

400

INVALID_DATA

INVALID_DATA top level error.
Value for attribute is too large (either in size or length).

The request contains an attribute value that is too large.

Given name must be less than or equal to 256 characters.
Image size must be less than 10MB.

UNIQUENESS_VIOLATION

400

INVALID_DATA

A request violated the uniqueness rule.

A resource with the specified name already exists.

An attempt to create a user having the same name as an existing user.
An attempt to create an environment having the same name as an existing environment.