About exceptions

The following section gives you an overview of the exceptions the SDK can throw. All exceptions that are passed to one of the callbacks are a D4LException. Every other exception that is thrown, and that doesn’t inherit from the D4LException class, is wrapped by a D4LException exception.

Recoverable exceptions

Depending on the operation, the SDK can throw the exceptions which are passed to the integrator application in the onError method of the respective callback. The exceptions can occur during the following operations:

  • Authorization

  • Encryption and decryption

  • File operations

  • Data validation

Authorization exceptions

Authorization exceptions can occur during any SDK operation that requires network requests, because all network requests are access-controlled and depend on a valid access token. When users are logged in and one of the exceptions is passed back to the callback function, the integrator application must log out the user. Afterwards, the user must log in again. During authorization, the SDK has these cases of exceptions.

Exception Description


Thrown when the cause is unknown.


Thrown when the user canceled the authorization/login request.


Thrown when the access token can’t be restored.


Thrown when the refresh token can’t be restored.


Thrown when the access token can’t be refreshed.


Thrown when the authorization state can’t be restored.


Thrown when the token state can’t be restored.


Thrown when the user can’t log in.

Cryptographic exceptions

During encryption and decryption, the SDK has these cases of exceptions.

Exception Description


Thrown when the key type is invalid


Thrown when the key version is invalid


Thrown when the encryption fails.


Thrown when the decryption fails.


Thrown when the key encryption fails.


Thrown when the key decryption fails.


Thrown when the key generation fails.


Thrown when fetching the key fails.

To recover from some of the cryptographic exceptions, follow these steps:

  1. Delete all stored cryptography keys.

    The integrator app displays the login screen again.

  2. Authorize the user again during login and the SDK generates new key pairs.

    Using the new key pairs, the user can run the operation again which led to the exception.

File exceptions

All files are stored encrypted in a BLOB storage service.

  • Each individual file is uploaded when a record is created or updated.

  • Files are downloaded when a record or attachment is downloaded.

During the upload and download of files, the SDK has these cases of exceptions.

Exception Description


Thrown when the download fails.


Thrown when the upload fails.

Data validation exceptions

During data validation, the SDK has these cases of exceptions.

Exception Description


Thrown when the SDK decrypts a record and the model version is higher than the version supported by the SDK. In this case, the integrator application must update the SDK and release a new version of the application to work with the previously unsupported record.


Thrown when the SDK uploads or downloads a record to the BLOB storage. When creating or updating a record with a new Attachment where the integrator application explicitly set an id attribute for the Attachment object with the message Attachment.id should be null. The exception is also thrown during the download of an Attachment object from the BLOB storage when the Attachment.id attribute isn’t set. The error message is Attachment.id expected.


Thrown when an expected field is missing for an upload or a download. The required field is needed to check the integrity of a file or attachment by using the attachment hash and attachment size for a document.


Thrown when the hash attachment is different from the hash obtained from the binary data. This validation is for an upload,update or a download. The hash validation failure indicates that the file integrity has been compromised.


Thrown when the given custom annotations contain a string, which is empty or is only composed of space characters. This validation applies on create, update and fetch.

Unrecoverable exceptions

The SDK can throw exceptions from which the integrator application can’t recover. These exceptions are a subclass of the D4LRuntimeException class when the SDK explicitly throws them. Or the exceptions are general java.lang.RuntimeException exceptions if something unexpectedly fails within the SDK.

The SDK explicitly throws these exceptions.

Exception Description


(Android only) Thrown when one of the parameters CLIENT_ID, CLIENT_SECRET, or REDIRECT_URL isn’t defined in the AndroidManifest.xml file.


Thrown when the passed client ID has an incorrect format. The client ID has two parts, separated by the # sign and the correct format is: partnerId#platformName.


(Android only) Thrown when during the SDK initialization, the SDK can’t access the applications metadata using the the PackageManager.


Thrown when there’s an attempt to execute an operation that the SDK doesn’t support.

With your consent, we will analyze your behavior on our website (d4l.io) to improve our offering for all users. If you consent to the transmission of analysis data, click “Accept”. You can withdraw your consent at any time in the privacy policy. More info: privacy policy).