--- title: Error codes description: 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. component: pingone-api page_id: pingone-api:platform:reference/error-codes canonical_url: https://developer.pingidentity.com/pingone-api/platform/reference/error-codes.html section_ids: top-level-error-messages: Top-level error messages detail-level-error-messages: Detail-level error messages --- # 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](#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](#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: ```json 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: ```json 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](../rate-limiting.html) 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. |