Status codes / error handeling
Introduction
In the Trust1Connector V3 we've completely reworked the error system. The goal of this system is to have error codes which are easy to read, understand and integrate. Our first implementation was a very generic approach with as few error codes as possible.
After some iterations of the Trust1Connector we've discovered that the old error system did not suffice the needs of integrators. So we've upgraded the system to be more consistent and extensive. This provides integrators the flexibility to have a very detailed error handeling system while keeping it easy to understand and read.
The new system provides information about the origin, type and detailed information of the error. We maintained the same type (integers) as our previous error codes, this makes it easier to differentiate them.
Status Codes
T1C uses response codes when handling a request.
In case of an error the response will contain a body with more detailed information about the error:
Error format
Error codes will be in the following number format XXXXXX for example 201010 is an error code that depicts an error occurred with the reader in the Transaction service.
The first digit depicts the Origin of that error, values can be the following;
Error | Origin |
1XXXXX | General |
2XXXXX | Transaction service |
3XXXXX | Certificate service |
4XXXXX | Meta service |
5XXXXX | File exchange |
6XXXXX | Identity service |
7XXXXX | Reader service |
8XXXXX | Proxy |
The following 2 digits describe the type of error;
Error | Type |
X01XXX | Reader |
X02XXX | Card |
X03XXX | Notification |
X04XXX | Security |
X05XXX | Configuration |
X06XXX | Input |
X07XXX | Session |
X08XXX | PIN |
X09XXX | PUK |
X10XXX | Pace |
X11XXX | Module |
X12XXX | System |
X13XXX | I/O |
X14XXX | Consent |
X15XXX | Agent |
Finally we have 3 digits that give a more detailed error. These will give you more information about the specific error-case. Currently we have the following exceptions that can be thrown.
Code | Exception type |
10000 | GeneralConnectorException |
XXX000 | InvalidDigestException |
XXX001 | ModuleNotSupportedException |
XXX002 | ModuleNotAvailableException |
XXX003 | ModuleNotImplementedException |
XXX004 | FunctionNotSupportedException |
XXX005 | FunctionNotAvailableException |
XXX006 | FunctionNotImplementedException |
XXX007 | ServiceNotSupportedException |
XXX008 | ServiceNotAvailableException |
XXX009 | ServiceNotImplementedException |
XXX010 | ReaderException |
XXX011 | ReaderTimeoutException |
XXX012 | ReaderProviderException |
XXX013 | ReaderNotAvailableException |
XXX014 | ReaderCancelledException |
XXX020 | InitialisationException |
XXX021 | DistributionServiceException |
XXX022 | GenericRestException |
XXX023 | JsonParseException |
XXX024 | JWTParseException |
XXX025 | ForbiddenException |
XXX026 | UnauthorisedException |
XXX028 | DeviceKeyStoreMissingException |
XXX029 | ParamRestException |
XXX030 | ProxyServiceException |
XXX031 | InvalidStateException |
XXX032 | DeviceKeyException |
XXX040 | TransactionException |
XXX041 | TransactionNotFoundException |
XXX042 | TransactionNotSupportedException |
XXX043 | TransactionProviderException |
XXX044 | ApplicationLockedException |
XXX045 | PaceLayerException |
XXX046 | TransactionPinBlockedException |
XXX047 | TransactionInvalidPinException |
XXX048 | TransactionPukBlockedException |
XXX049 | TransactionInvalidPukException |
XXX050 | TransactionPinTimeoutException |
XXX051 | TransactionPinCancelledException |
XXX052 | TransactionSignAuthenticateErrorException |
XXX053 | CardProtocolException |
XXX054 | ApduException |
XXX060 - XXX069 | TransactionPukException |
XXX070 - XXX079 | TransactionPinException |
XXX090 | EncryptionException |
XXX100 | CertificateException |
XXX101 | CertificatePinException |
XXX102 | CertificateNotFoundException |
XXX103 | CertificateProviderException |
XXX104 | MetaException |
XXX105 | MetaPinException |
XXX106 | MetaNotFoundException |
XXX107 | MetaProviderException |
XXX110 | PKCS11Exception |
XXX111 | PKCS11ProviderException |
XXX120 | FileExchangeException |
XXX121 | IoException |
XXX123 | AccessException |
XXX124 | TypeException |
XXX125 | EntityException |
XXX126 | ConfigurationException |
XXX127 | ContentException |
XXX128 | AccessReadException |
XXX129 | AccessWriteException |
XXX130 | AccessExecuteException |
XXX131 | FileNotFoundException |
XXX132 | FileAlreadyExistsException |
XXX133 | TypeAlreadyExistsException |
XXX135 | MatrixPrinterException |
XXX140 | NotificationException |
XXX998 | InternalErrorException |
XXX999 | ConnectorNotAvailableException |
XXX501 | ConsentException |
XXX500 | AgentNotFoundException |
XXX200 | InvalidSessionException |
XXX201 | InvalidAtrException |
XXX996 | ClientErrorException (invalid input body or request was send) |
XXX997 | SandboxRuntimeException (failure in the sanbox, API will implicitly restart the sandbox) |
Codes to expect
The following list are codes that you can expect.
General / Controller
Error code | Description |
111003 | Module not implemented |
106029 | Parameter error |
105126 | Configuration error |
112031 | Invalid T1C state error |
104025 | Forbidden exception |
814501 | Consent error |
815500 | Agent not found |
104000 | Invalid digest error |
104021 | Error contacting or retrieving info from Distribution service |
104020 | Error initialising T1C |
104030 | Error contacting or getting info from the proxy |
104028 | Device keystore missing |
104027 | DS JWE error |
104026 | Unauthorised |
104027 | Forbidden |
104024 | JWT parsing error |
104023 | JSON parsing error |
100890 | Decryption exception, pin or puk or pace value could not be decrypted |
106997 | Invalid input body or request has been send to the API |
Aventry My Id 4
Error code | Description |
312998 | Module not implemented |
611004 | Parameter error |
411004 | Invalid T1C state error |
212998 | Forbidden exception |
211004 | Function not supported |
202040 | Card error |
302040 | Card error |
402040 | Card error |
602040 | Card error |
206029 | Parameter exception |
208072 | invalid Pin 2 retries remain |
208071 | invalid Pin 1 retry remain |
206046 | Pin blocked |
206047 | invalid pin |
201051 | Pin cancelled |
2015050 | Pin timeout |
209048 | Puk blocked |
209049 | invalid puk |
209062 | Invalid puk 2 retries remain |
209061 | invalid puk 1 retry remain |
202010 | Card not present |
302010 | Card not present |
602010 | Card not present |
Oberthur 7.3
Error code | Description |
312998 | Module not implemented |
611004 | Parameter error |
411004 | Invalid T1C state error |
212998 | Forbidden exception |
211004 | Function not supported |
202040 | Card error |
302040 | Card error |
402040 | Card error |
602040 | Card error |
206029 | Parameter exception |
208072 | invalid Pin 2 retries remain |
208071 | invalid Pin 1 retry remain |
206046 | Pin blocked |
206047 | invalid pin |
201051 | Pin cancelled |
2015050 | Pin timeout |
202010 | Card not present |
302010 | Card not present |
602010 | Card not present |
Idemia cosmo 8.2
Error code | Description |
312998 | Module not implemented |
611004 | Parameter error |
411004 | Invalid T1C state error |
212998 | Forbidden exception |
211004 | Function not supported |
202040 | Card error |
302040 | Card error |
402040 | Card error |
602040 | Card error |
206029 | Parameter exception |
208072 | invalid Pin 2 retries remain |
208071 | invalid Pin 1 retry remain |
206046 | Pin blocked |
206047 | invalid pin |
201051 | Pin cancelled |
2015050 | Pin timeout |
202010 | Card not present |
302010 | Card not present |
602010 | Card not present |
BeID
Error code | Description |
312998 | Module not implemented |
611004 | Parameter error |
411004 | Invalid T1C state error |
212998 | Forbidden exception |
211004 | Function not supported |
202040 | Card error |
302040 | Card error |
402040 | Card error |
602040 | Card error |
206029 | Parameter exception |
208072 | invalid Pin 2 retries remain |
208071 | invalid Pin 1 retry remain |
206046 | Pin blocked |
206047 | invalid pin |
201051 | Pin cancelled |
2015050 | Pin timeout |
202010 | Card not present |
302010 | Card not present |
602010 | Card not present |
Diplad
Error code | Description |
312998 | Module not implemented |
611004 | Parameter error |
411004 | Invalid T1C state error |
212998 | Forbidden exception |
211004 | Function not supported |
202040 | Card error |
302040 | Card error |
402040 | Card error |
602040 | Card error |
206029 | Parameter exception |
208072 | invalid Pin 2 retries remain |
208071 | invalid Pin 1 retry remain |
206046 | Pin blocked |
206047 | invalid pin |
201051 | Pin cancelled |
2015050 | Pin timeout |
202010 | Card not present |
302010 | Card not present |
602010 | Card not present |
Luxtrust
Error code | Description |
312998 | Module not implemented |
611004 | Parameter error |
411004 | Invalid T1C state error |
212998 | Forbidden exception |
211004 | Function not supported |
202040 | Card error |
302040 | Card error |
402040 | Card error |
602040 | Card error |
206029 | Parameter exception |
208074 | invalid Pin 4 retries remain |
208073 | invalid Pin 3 retries remain |
208072 | invalid Pin 2 retries remain |
208071 | invalid Pin 1 retry remain |
206046 | Pin blocked |
206047 | invalid pin |
201051 | Pin cancelled |
2015050 | Pin timeout |
202010 | Card not present |
302010 | Card not present |
602010 | Card not present |
Luxeid
Error code | Description |
312998 | Module not implemented |
611004 | Parameter error |
411004 | Invalid T1C state error |
212998 | Forbidden exception |
211004 | Function not supported |
202040 | Card error |
302040 | Card error |
402040 | Card error |
602040 | Card error |
206029 | Parameter exception |
208074 | invalid Pin 4 retries remain |
208073 | invalid Pin 3 retries remain |
208072 | invalid Pin 2 retries remain |
208071 | invalid Pin 1 retry remain |
206046 | Pin blocked |
206047 | invalid pin |
201051 | Pin cancelled |
2015050 | Pin timeout |
209048 | Puk blocked |
209049 | invalid puk |
209064 | Invalid puk 4 retries remain |
209063 | Invalid puk 3 retries remain |
209062 | Invalid puk 2 retries remain |
209061 | invalid puk 1 retry remain |
202010 | Card not present |
302010 | Card not present |
602010 | Card not present |
EMV
Error | Description |
312998 | Module not implemented |
611004 | Parameter error |
411004 | Invalid T1C state error |
212998 | Forbidden exception |
211004 | Function not supported |
202040 | Card error |
302040 | Card error |
402040 | Card error |
602040 | Card error |
206029 | Parameter exception |
208072 | invalid Pin 2 retries remain |
208071 | invalid Pin 1 retry remain |
206046 | Pin blocked |
206047 | invalid pin |
201051 | Pin cancelled |
2015050 | Pin timeout |
202010 | Card not present |
302010 | Card not present |
602010 | Card not present |
Crelan
Error | Description |
312998 | Module not implemented |
611004 | Parameter error |
411004 | Invalid T1C state error |
212998 | Forbidden exception |
211004 | Function not supported |
202040 | Card error |
302040 | Card error |
402040 | Card error |
602040 | Card error |
206029 | Parameter exception |
208072 | invalid Pin 2 retries remain |
208071 | invalid Pin 1 retry remain |
206046 | Pin blocked |
206047 | invalid pin |
201051 | Pin cancelled |
2015050 | Pin timeout |
202010 | Card not present |
302010 | Card not present |
602010 | Card not present |
File exchange
Error | Description |
505126 | Configuration error / none is found |
504123 | Access exception/ not enough access rights - General error |
513121 | I/O error |
504128 | Read rights missing |
504129 | Write rights missing |
504130 | Execute rights missing |
513124 | Type error |
513125 | Entity error |
513127 | Content error / file not found |
503140 | Notification error, when a OS dialog returns an error |
513131 | File not found |
513132 | File already exists |
Error codes coming from v2
Old code | New code | example description |
351 | 504128 | /Library/Updates/ProductMetadata2.plist (Operation not permitted) |
352 | 504129 | /Library/Updates/ProductMetadata2.plist (Operation not permitted) |
353 | 504130 | /Library/Updates/ProductMetadata2.plist (Operation not permitted) |
354 | 513121 | Source '/Users/gilles/Desktop/fileextest/test.plist' does not exist |
355 | 503140 | No valid dir path returned, no valid file path returned, Timeout, No PIN entered |
356 | 513124 | No Type with name test was found in entity with name testEnt, |
357 | 513124 | type with name testType already exists |
358 | 513131 or 513132 | FIle not found or File already exists |
359 | not applicable | |
360 | 513125 | Entity with name testEnt already exists |
361 | 513125 | No Entity with name testEnt was found |
/ | 505126 | No configuration found (file-exchange config file is missing/deleted…) |
Last updated