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:

{
  description: "some error description",
  code: "some error code"
}

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

9XXXXX

System

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

XXX300

SecurityException

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 updated