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:
1
{
2
description: "some error description",
3
code: "some error code"
4
}
Copied!

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…)

Simple error handeling

The most simple way you can check the error codes is by only taking into account the latest 3 digits. The first 3 digits provide information about the Context and environment
Last modified 4mo ago