Managing errors
During AutomatID initialization and identification flows, several error conditions may arise. Each error is modeled with a domain (string) and a code (integer).
On Android, errors are modeled by the AutomatIdError class. Its nested classes Domains and Codes list the possible values as constants.
On iOS, error domains are modeled as strings while error codes are exposed as an NSEnum and the possible values are in the code documentation for the attributes of the AutomatIDResultError class.
Errors can be recoverable or unrecoverable.
Recoverable errors
Recoverable errors are error situations that may arise during an identification flow and that do not require the identification flow to be aborted and AutomatID UI to be closed. The user can be allowed to try again without going back to your app.
The following table shows the possible recoverable errors:
| Domain | Error code name | Error code value | Raised by which SDK method | Description | Suggested error handling |
|---|---|---|---|---|---|
| server.generic_error | GENERIC_ERROR | 500 | startIdentification | An internal error during the identification flow has happened. | Present an error to the user and ask them to retry again later. |
| server.document_error | EXPIRED_DOCUMENT | 503 | startIdentification | The presented document is expired. | Present an error to the user asking them to retry with a document that is not expired. |
| server.document_error | INVALID_DOCUMENT_DATA | 506 | startIdentification | The data read from the document via NFC is corrupted. | Present an error to the user asking them to retry with a valid document. |
| server.face_error | TOO_MANY_FACES | 501 | startIdentification | During the liveness check, more than one person's face have been detected by the camera. | Present an error to the user asking them to make sure to be alone while performing the liveness check. |
| server.face_error | NO_FACE_MATCH | 502 | startIdentification | The face acquired during the liveness check doesn't match with the person's photo extracted from the document. | The user may be trying to use a document that is not their own. Present an error to the user asking them to use their own document. |
| server.card_error | NO_CARD_MATCH | 505 | startIdentification | The card presented by the user is not the card that was expected (the read card data doesn't match the JWT card data). | Present an error to the user asking them to retry with a valid credit/debit card. |
| server.card_error | EXPIRED_CARD | 510 | startIdentification | The credit/debit card presented by the user is expired. | Present an error to the user asking them to retry with a credit/debit card that is not expired. |
When such an error arises, the decideRecoverableErrorHandling() method of your callback is invoked, and the error that occurred is provided to you. Here, you can choose how to treat this error and decide whether the identification flow should allow the user to try again, or the identification flow should be aborted. Depending on your business needs, you could choose to allow the user to always try again, to always abort the identification, or adopt a more complex decision policy. For example, you may want to allow the user to try again up to a certain number of times, after which the identification flow should be aborted. The outcome of your decision must be returned from the onRecoverableError(): the possible values are RETRY_IDENTIFICATION or ABORT_IDENTIFICATION.
If you returned RETRY_IDENTIFICATION, depending on the error, the user will be brought back to the flow at a suitable point where they can try again. For example, if the user provided an expired document, they are brought back to the beginning of the flow; if they failed the liveness check, they will need to perform it again.
If you returned ABORT_IDENTIFICATION, AutomatID will abort the identification flow and the user will be brought back to your app. The onError() method of your callback will be invoked with the error.
Unrecoverable errors
Unrecoverable errors are error situations that may arise during AutomatID initialization or the identification flow, and that will cause the identification flow to be aborted or to never start.
The following table shows the possible unrecoverable errors:
| Domain | Error code name | Error code value | Raised by which SDK method | Description | Suggested error handling |
|---|---|---|---|---|---|
| plugin.configuration | CONFIG_FILE_IS_EMPTY | 1 | init | The configuration file that was passed to the init() method is empty. | Please verify that the correct configuration file is present in the app build and that its path is correct and provided to the init() method. |
| plugin.configuration | CONFIG_FILE_DECRYPTION_FAILED | 2 | init | The configuration file that was passed to the init() method is corrupted. | Please verify that the correct configuration file is present in the app build and that its path is correct and provided to the init() method. |
| plugin.configuration | CONFIGURATION_FILE_MALFORMED | 3 | init | The configuration file that was passed to the init() method is corrupted. | Please verify that the correct configuration file is present in the app build and that its path is correct and provided to the init() method. |
| plugin.configuration | INTEGRITY_CHECK_ON_CONFIG_FILE_FAILED | 4 | init | The configuration file that was passed to the init() method is corrupted. | Please verify that the correct configuration file is present in the app build and that its path is correct and provided to the init() method. |
| plugin.configuration | APP_ID_CHECK_FAILED | 5 | init | The configuration file that was passed to the init() method was not generated for the current application. Specifically, the application id doesn't match. | Please verify that the correct configuration file is present in the app build and that its path is correct and provided to the init() method. |
| plugin.configuration | SDK_MIN_VERSION_CHECK_FAILED | 6 | init | The version of AutomatID does not match what is expected in the configuration file. | Please verify that the correct configuration file is present in the app build and that its path is correct and provided to the init() method. Please verify you are using the expected version of the SDK. |
| plugin.configuration | GENERIC_CONFIG_FILE_READ_AND_PARSING_ERROR | 7 | init | There was an error reading the configuration file. | Please verify that the correct configuration file is present in the app build and that its path is correct and provided to the init() method. |
| plugin.configuration | UNABLE_TO_OPEN_THE_CONFIG_FILE | 8 | init | There was an error opening the configuration file. | Please verify that the correct configuration file is present in the app build and that its path is correct and provided to the init() method. |
| plugin.invocation | INVOCATION_WITHOUT_INIT | 9 | startIdentification | An identification has been requested but init() was not called. | Please call the init() method and verify it completed without errors before calling the startIdentification() method. |
| plugin.invocation | INVALID_PARAMETERS | 10 | startIdentification | An invalid identification request has been passed to the startIdentification() method. | If the card scan was selected to be used, a valid cardScanData parameter must be provided. |
| plugin.device_compatibility | NFC_READER_IS_NOT_PRESENT | 11 | startIdentification | The device is not equipped with NFC hardware. | The identification cannot be performed through AutomatID. The app may propose a different identification workflow. |
| invalid_response | MALFORMED_SUCCESS_RESPONSE | 12 | startIdentification | An internal error during the identification flow has happened. | Present an error to the user and notify Opentech of the error. |
| invalid_response | MALFORMED_ERROR_RESPONSE | 13 | startIdentification | An internal error during the identification flow has happened. | Present an error to the user and notify Opentech of the error. |
| identification_flow | USER_TAPPED_FALLBACK_BUTTON | 14 | startIdentification | The user tapped the fallback button in the identification flow. | The user has tapped the fallback button. The identification is closed. |
| server.card_error | NOT_RECOVERABLE_ERROR | 522 | startIdentification | There was an error in the decryption of the payment card JWT. | Please verify that you are constructing and encrypting the JWT with the correct key and according to the documentation. |
| server.generic_error | BILLING_ERROR | 523 | startIdentification | The user is not enabled to perform the identification (Not registered or contract expired) | Please review the status of your contract on AWS Marketplace to ensure that the billing information are valid and up to date. |
| server.generic_error | PROJECT_NOT_FOUND | 402 | startIdentification | The project where this app was created does not esist (i.e. it was deleted) | The deletion of the AutomatID project is irreversible. You cannot use AutomatID in this app any longer. |
| server.generic_error | APPLICATION_NOT_FOUND | 403 | startIdentification | The app on AutomatID portal does not esist (i.e. it was deleted) | The deletion of the AutomatID app is irreversible. You cannot use AutomatID in this app any longer. |
When such an error arises, only the onError() method of your callback is invoked, and the error that occurred is provided to you. The identification flow will be aborted automatically and AutomatID will close.
Errors with domain plugin.configuration and plugin.invocation denote an error that happens during the integration of AutomatID in the development phases, for example related to the usage of a wrong or corrupted configuration file, or the integration of a configuration file that was generated for a certain application, in another application (identified by the application id). Please examine the suggested error handling in the table for guidance.