Error handling in PingID SDK

Errors generated by an API should return a response payload formatted as per the schema below. Errors generated by a PingID SDK API should allow the developer to resolve specific errors programmatically.

An error response consists of:

A highlevel error code that must be handled by the customer server.
(Optional) A details element that contains specific information on how to resolve the fault.

Error representation

Attribute	Required	Description
id	Yes	A unique identifier that is stored in log files that can be used to track the error received on the customer server with server-side activity for troubleshooting purposes.
code	Yes	General fault code which the customer server must handle to provide all exception handling routines and to localize messages to end users. Top level error handling must be implemented by the customer server developer. The top level error codes are listed below.
message	Yes	Short description of the error. This message is intended to assist the developer with debugging, and is returned in English only.
target	No	The item that caused the error. For example, a form field id or an attribute inside a JSON object.
details	No	Additional details about the error. This provides further information to the user about the error, and provides the customer server developer more detailed error messages to help resolve the error, and to display to the end users. Errors described inside the “details” object are optional, and may be implemented by the customer server or API developer. See the “details” object structure below.

“details” object representation

The “details” object is array of objects. Each object may contain the following attributes:

Attribute	Required	Description
code	Yes	Refer to the detailed error codes listed below.
message	No	Short description of the error. This message is intended to assist the developer with debugging, and is returned in English only.
target	No	The item that caused the error. For example, a form field id or an attribute inside a JSON object.

Top level error codes

These codes must be handled by all customer servers. Where not specified, a response code of 400 should be returned.

Code	HTTP status code	Description
FORBIDDEN	403 (Forbidden)	This status can be returned under the following circumstances: PingID SDK voice and SMS services have been disabled. PingID SDK services have been disabled.
INVALID_DATA	400 (Bad Request)	A valid request was received, however the request could not be completed as there were one or more validation errors with the contents of the request.
INVALID_REQUEST	400 (Bad Request)	The request was invalid and could not be executed. For example a POST request was made without a body.
NOT_FOUND	404 Not Found	The requested resource does not exist.
REQUEST_FAILED	400 (Bad Request)	A valid request was received, however the operation could not be completed due to an issue during the request.
UNAUTHORIZED	401 Unauthorized	The requestor does not have valid authentication credentials to complete the request.
UNEXPECTED_ERROR	500 Internal Server Error	An unexpected server error occurred.

Detailed error codes

These codes are optional for a customer server to handle, and are “child” errors of top level error codes nested in the “details” attribute of the error. These values provide the developer with hints on how to resolve errors.

Code	Description
APPLICATION_DISABLED	This application is marked as disabled.
APPLICATION_SHARED_WITH_NON_EXIST_ID	A customer tried to share an application between 2 tenants, but the provided application id doesn’t exist.
CANCELED	This error is returned when an action on a resource failed, because the resource is canceled. For example, attempting to cancel an authentication token which was already canceled.
CLAIMED	This error is returned when an action on a resource failed, because the resource is claimed. For example, attempting to cancel an authentication token which was already claimed.
DEVICE_BLOCKED	This internal error code appears in 2 cases: When a customer server is trying to create a registration token for a blocked device. When a user tries to authenticate from an accessing device, but this device is marked as blocked.
DEVICE_IGNORED	This internal error code appears in 2 cases: When a customer server is trying to create a registration token for an ignored device. When a user tries to authenticate from an accessing device, but this device is marked as ignored.
DEVICE_ROOTED	The user’s device is detected as having been rooted or jailbroken.
EMAIL_NOT_ENABLED	This error may occur in 2 scenarios: A user tried to pair an email device when email pairing is disabled for the application. The admin disabled email as an alternate authentication method. After this change it can take up to 2 minutes until all users are unpaired from the email devices. If during these 2 minutes users attempt to authenticate using their email devices, this error will be triggered.
EMPTY_VALUE	NULL value supplied
FCM_FAIL_TO_CONNECT	Credentials for the FCM service are not valid.
INVALID_ACCOUNT	Request is made on / by an account that is not verified or has been suspended.
INVALID_PATTERN	Received a value, but this value does not match the pattern.
INVALID_PRODUCTION_CERTIFICATE	A customer tried to upload an invalid Production iOS Certificate for Apple Push Notification Service to the PingID SDK server.
INVALID_SANDBOX_CERTIFICATE	A customer tried to upload an invalid Sandbox iOS Certificate for Apple Push Notification Service to the PingID SDK server.
INVALID_USER_STATUS	A customer tried to create a registration token via the REST API for an active user.
INVALID_VALUE	Value is invalid due to validation rules.
NO_MOBILE_ACTIVE_DEVICES	This error is returned when attempting to create an authentication token for a user who has no mobile app devices.
NOT_FOUND	Request references a resource that does not exist.
OUT_OF_RANGE	Value is out of range.
PRODUCTION_CERTIFICATE_EXPIRED	A customer tried to upload an expired Production iOS Certificate for Apple Push Notification Service to the PingID SDK server.
PRODUCTION_CERTIFICATE_FAIL_TO_CONNECT	There is a problem with the connection to Apple Push Notification Server (Production). There is the possibility that the certificate was revoked.
REQUIRED_VALUE	Required attribute was omitted in request.
RESOURCE_ALREADY_EXISTS	A customer server tried to create a resource that already exists.
RESOURCE_IN_USE	User tried to use a resource, but this resource is already in use.
RETRY_LIMIT_EXCEEDED	User reached the maximum permitted number of incorrect retry attempts, for example, by entering 3 incorrect OTPs in succession.
SANDBOX_CERTIFICATE_EXPIRED	A customer tried to upload an expired Sandbox iOS Certificate for Apple Push Notification Service to the PingID SDK server.
SANDBOX_CERTIFICATE_FAIL_TO_CONNECT	There is a problem with the connection to Apple Push Notification Server (Sandbox). There is the possibility that the certificate was revoked.
SERVICE_ERROR	An error with the service occurred.
SIZE_LIMIT_EXCEEDED	Value is too large for the attribute.
SMS_NOT_ENABLED	A user tried to pair an SMS device, or authenticate with an SMS device, when SMS pairing and authentication is disabled for the application. Refer to Update a PingID SDK app’s configuration for details.
SMS_QUOTA_EXCEEDED	This internal error indicates that the SMS and Voice daily authentication quota was exceeded for the account or for the user.
SMS_VOICE_SUSPENDED	PingID SDK voice and SMS services have been disabled.
UNINSTALLED_APPLICATION	A user reinstalled an app on a device, and then using that device, attempted to authenticate another device.
UNIQUE_VALUE_REQUIRED	Value should be unique.
USER_DISABLED	User marked as suspended.
USER_NOT_ACTIVE	This error is returned when an action failed, because the user is not active (has no devices). For example, when attempting to create a QR code for a non-active user.
VOICE_NOT_ENABLED	A user tried to pair a voice device, or authenticate with an voice device, when voice pairing and authentication is disabled for the application. Refer to Update a PingID SDK app’s configuration for details.
VOICE_QUOTA_EXCEEDED	This internal error indicates that the SMS and Voice daily authentication quota was exceeded for the account or for the user.

Error handling examples

General error example

{
"id" : "abcd123qwe",
"code" : "INVALID_DATA",
"message" : "The data provided was invalid",
"details" : [
 {
  "code" : "EMPTY_VALUE",
  "target" : "givenName",
  "message" : "Given name can not be empty."
 },
 {
  "code" : "OUT_OF_RANGE",
  "target" : "age",
  "message" : "Age must be between 1 and 150.",
  "innerError" : {
   "rangeMinimumValue" : 1,
   "rangeMaximumValue" : 150
  }
 }]
}

Disabled application error example

The following authentication request:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ \ 
	"authenticationType": "AUTHENTICATE" }' \
	 'https://sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-d8b91d83fda4/applications/48cf7277-a5ea-48ea-b526-c4784230c396/users/john.galt/authentications'

Returns the following “REQUEST_FAILED” status:

{
  "message": "Application disabled",
  "target": "application",
  "id": "webs_a14fae49-f82d-4e72-8e00-8d2ae11610af",
  "details": [
    {
      "message": "Application disabled",
      "code": "APPLICATION_DISABLED"
    }
  ],
  "code": "REQUEST_FAILED"
}

Note: The specific flow of of how to proceed after receiving an error should be built into the customer server application, since error recovery logic differs between applications.