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

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.

DEVICE_BLOCKED

This internal error code appears in 2 cases:

  1. When a customer server is trying to create a registration token for a blocked device.
  2. 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:

  1. When a customer server is trying to create a registration token for an ignored device.
  2. When a user tries to authenticate from an accessing device, but this device is marked as ignored.

EMAIL_NOT_ENABLED

This error may occur in 2 scenarios:

  1. A user tried to pair an email device when email pairing is disabled for the application.
  2. 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.

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, he entered 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 daily quota was exceeded for the account or for the user.

UNIQUE_VALUE_REQUIRED

Value should be unique.

USER_DISABLED

User marked as suspended.

Error handling examples

General 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
  }
 }]
}

Example of a returned error, in a case where an application was disabled:

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"
}