Error Codes

This document provides a comprehensive reference for all error codes returned by the Arculus FIDO Server and mobile SDKs.

Response Format

All API responses follow a standard JSON format:

{
  "status": "ok | failed | false",
  "errorMessage": "Error description or empty string",
  "statuscode": "HTTP status code (as string, optional)",
  "responseCode": 200
}

Note: The status field may be "ok" for success, "failed" for most errors, or "false" for session-related errors. The statuscode field (as a string) is included in error responses.

HTTP Status Codes

Code	Reason	Description
200	Success	Operation completed successfully
400	Bad Request	Invalid JSON or malformed request (see E* codes)
401	Unauthorized	Authentication failed (see E* codes)
403	Forbidden	No account for user (see E* codes)
408	Request Timeout	Session expired (see E* codes)
507	Insufficient Storage	Server unable to store data (see E* codes)

Card Error Codes (600-617)

These errors originate from the Arculus FIDO card during NFC communication:

Code	Error	User-Facing Message	Recovery Action
600	Tag Lost	"Please hold your card steady and try again"	Retry - keep card still on device
601	Unknown Error	"An error occurred. Please try again"	Retry operation
602	No Credentials	"No credentials found. Please register first"	Complete registration flow
603	User Not Found	"User not found on card. Please register"	Register the card for this user
604	Signature Failed	"Card operation failed. Please try again"	Retry operation
605	Device Reset Failed	"Card reset failed. Please try again"	Retry reset operation
606	Keystore Full	"Card storage full. Remove unused credentials"	Delete old credentials from card
607	Transmit Failed	"Connection lost. Please try again"	Retry - ensure card is positioned correctly
608	Get PIN Token Failed	"Invalid PIN. Please check your PIN"	Verify PIN is correct
609	Get Public Key Failed	"PIN verification failed"	Verify PIN is correct
610	Applet Select Failed	"Unrecognized card. Use an Arculus FIDO card"	Use a valid Arculus FIDO2 card
611	Set PIN Failed	"Failed to set PIN. Please try again"	Retry with valid 6+ digit PIN
612	Change PIN Failed	"Failed to change PIN. Check your current PIN"	Verify old PIN is correct
613	Internal Crypto Error	"Card error. Please try again"	Retry operation
614	NFC Timeout	"Connection timed out. Hold card steady"	Retry - keep card on device longer
615	NFC Not Available	"NFC not available on this device"	Use a device with NFC support
616	Tag Lost (Card Moved)	"Card moved during operation. Try again"	Retry - hold card still
617	Transmit Error (Card Moved)	"Card moved during operation. Try again"	Retry - hold card still

Server Error Codes (E0xxx - E4xxx)

Request Validation Errors (E00xx)

Code	Error Message	Cause
E0000R	Date malformed	Invalid date format in request
E0001R	Date malformed	Invalid date format in request
E0002R	Type not supplied	Missing type field
E0003R	Type not string	type field is not a string
E0004R	Type not set to public-key	Invalid credential type
E0005R	id not supplied	Missing credential ID
E0006R	id is not base64url	Invalid ID encoding
E0007R	Signature is not base64url	Invalid signature encoding
E0008R	clientDataJSON is not base64url	Invalid client data encoding
E0009R	tokenBinding not supported	Token binding is deprecated
E0010R	response is not dict	Response must be a dictionary
E0011R	Type not supplied	Missing type in response
E0012R	Type not string	Type in response is not a string
E0013R	Type not set to public-key	Invalid type in response
E0014R	id not supplied	Missing ID in response
E0015R	id is not base64url	Invalid ID encoding in response
E0016R	authenticatorData missing	Missing authenticator data
E0017R	authenticatorData missing	Missing authenticator data
E0018R	authenticatorData is not base64url	Invalid authenticator data encoding
E0019R	Signature is not base64url	Invalid signature encoding
E0020R	clientDataJSON is not base64url	Invalid client data encoding
E0021R	clientDataJSON missing	Missing client data JSON
E0022R	tokenBinding not supported	Token binding is deprecated
E0023R	Invalid JSON due to keypair for deviceinfo	Malformed deviceinfo JSON
E0024R	Session expired	Registration/auth session timed out
E0025R	Unknown relying party / register failed / multitenant error	Relying party not found, registration failed, or multitenant configuration issue
E0026R	Server is unable to store / Invalid X-ArculusFido-RelyingParty header	Database storage failed or invalid header format
E0027R	Session expired	Session timed out
E0028R	Server is unable to store Authenticator increment count	Counter update failed
E0029R	authenticate failed	Authentication operation failed

Attestation Errors (E10xx)

Code	Error Message	Cause
E1000R	AAGUID must be 16 bytes	Invalid AAGUID length
E1001R	Wrong length	Invalid data length
E1002R	Wrong length	Invalid data length
E1003R	fmt fido-u2f AAGUID is 00000000-0000-0000-0000-000000000000	Invalid U2F AAGUID
E1004R	attStmt alg field missing	Missing algorithm field
E1005R	attStmt alg is not type number	Algorithm must be numeric
E1006R	attStmt sig field missing	Missing signature field
E1007R	attStmt sig is not bytes	Signature must be bytes
E1008R	attStmt sig is empty byte string	Empty signature
E1009R	ALG does not match metadata	Algorithm mismatch with metadata
E1010R	Attestation certificate must use version 3!	Certificate version error
E1011R	Attestation certificate must have CA=false!	Invalid certificate CA flag
E1012R	Attestation certificate must have Basic Constraints!	Missing basic constraints
E1013R	Chain Version V3 error	Certificate chain version error
E1014R	Chain Version V3 error	Certificate chain version error
E1015R	Invalid signature order	Wrong signature order
E1016R	x5c leaf certificate expired	Certificate has expired
E1017R	Attestation Signature for x5c is invalid	Invalid certificate signature
E1018R	Attestation certificate AAGUID must match authenticator data	AAGUID mismatch
E1019R	'id-fido-gen-ce-aaguid' extension must not be marked critical	Extension criticality error
E1020R	fido-u2f x5c is missing	Missing U2F certificate
E1021R	fido-u2f attStmt.x5c is not of type ARRAY	Certificate must be array
E1022R	fido-u2f x5c must be one certificate	Too many certificates (or x5c is missing)
E1023R	Fido_u2 public key is not Elliptic Curve (EC) public key over the P-256 curve	Invalid U2F public key type
E1024R	Fido_u2 public credentialPublicKey is not CBOR -7	Invalid U2F algorithm
E1025R	Attestation Signature for Fido_u2f is invalid	Invalid U2F signature
E1026R	Android att_stmt is missing	Missing Android attestation
E1027R	Android x5c is missing	Missing Android certificate
E1028R	Android sig is missing	Missing Android signature
E1029R	Android x5c is missing	Missing Android certificate
E1030R	Android attStmt.x5c is not of type ARRAY	Certificate must be array
E1031R	Android x5c is missing	Missing Android certificate
E1032R	Attestation Signature for Android is invalid	Invalid Android signature
E1033R	x5c certificate does not match credentialPublicKey	Key mismatch
E1034R	alg does not match credentialPublicKey	Algorithm mismatch with credential public key
E1035R	Packed self attestation SIGNATURE invalid	Invalid self-attestation
E1036R	MDS Entry not Found for AAGUID	Authenticator metadata not found
E1037R	MDS validation error	Metadata service validation failed (see error message)
E1038R	Invalid Attestation Payload. MDS Violation. x5c object present while BASIC_SURROGATE specified	Attestation format conflict with MDS
E1039R	'fmt' field is missing	Missing format field
E1040R	'fmt' format is unknown	Unknown attestation format
E1041R	'fmt' none and FULL packed	Format conflict
E1042R	'x5c' missing	Missing certificate chain
E1043R	attStmt.x5c is not of type ARRAY	Certificate must be array
E1044R	attStmt.x5c is an EMPTY ARRAY	Empty certificate chain
E1045R	AAGUID is None and NOT in Whitelist of AAGUIDs	Missing AAGUID and not whitelisted
E1046R	Whitelist is ON and yet no Whitelist of AAGUIDs exists	AAGUID whitelist enabled but empty
E1047R	AAGUID NOT in Whitelist of AAGUIDs	AAGUID not in whitelist

Verification Errors (E20xx)

Code	Error Message	Cause
E2000R	Custom challenge must be of type 'bytes'	Invalid challenge type
E2001R	Custom challenge length must be >= 16	Challenge too short
E2002R	Server has no allowed algorithms	No algorithms configured
E2003R	incorrect arguments passed to register_complete()	Invalid registration args
E2004R	Incorrect type in CollectedClientData	Invalid client data type
E2005R	Invalid origin in CollectedClientData	Origin mismatch
E2006R	Wrong challenge in response	Challenge mismatch
E2007R	Wrong RP ID hash in response	Relying party mismatch
E2008R	User Present flag not set	User presence not verified
E2009R	User verification required, but User Verified flag not set	User verification required during registration
E2010R	incorrect arguments passed to authenticate_complete()	Invalid auth args
E2011R	Incorrect type in CollectedClientData	Invalid client data type
E2012R	Invalid origin in CollectedClientData	Origin mismatch
E2013R	Wrong challenge in response	Challenge mismatch
E2014R	Wrong RP ID hash in response	Relying party mismatch
E2015R	User Present flag not set	User presence not verified
E2016R	User verification required, but user verified flag not set	User verification required during authentication
E2017R	Invalid signature	Signature verification failed
E2018R	ServerAuthenticatorAssertionResponse counter error	Authenticator counter not increased correctly
E2019R	Unknown credential ID	Credential not found

Parsing Errors (E30xx)

These errors occur during data parsing and validation:

Code	Error Message	Cause
E3000R	Not enough data to read	Insufficient data in buffer
E3001R	Error parsing field	Field parsing failed (see error message)
E3002R	Error parsing Invalid Signature	Signature parsing failed
E3003R	Error parsing field	Field parsing failed (see error message)
E3004R	Key error	Missing required key in data structure
E3005R	from_dict called with non-Mapping data	Invalid data type for dictionary conversion

TPM Attestation Errors (E40xx)

Code	Error Message	Cause
E4000R	Certificate should not have Subject	Invalid TPM certificate
E4001R	Certificate should have SubjectAlternativeName	Missing SAN
E4003R	TPM att_stmt missing	Missing TPM attestation
E4004R	TPM version 2.0 only supported	Unsupported TPM version
E4005R	TPM missing pubarea	Missing public area
E4006R	TPM public_key is not same as auth_data	Key mismatch
E4007R	tpm certInfo.magic is not set to TPM_GENERATED_VALUE	Invalid TPM magic
E4010R	TPM extradata is not equal to attToBeSignedHash	Hash mismatch
E4011R	TPM 'x5c' missing	Missing TPM certificate
E4013R	TPM error Subject sequence is empty	Empty subject
E4014R	x5c leaf certificate expired	Certificate expired
E4015R	Missing certificate extension extKeyUsage(2.5.29.37)	Missing key usage
E4016R	Missing tcg-kp-AIKCertificate OID in extendedKeyUsage	Missing AIK OID
E4017R	Attestation certificate AAGUID must match authenticator data	AAGUID mismatch
E4018R	'id-fido-gen-ce-aaguid' extension must not be marked critical	Extension error
E4019R	Attestation Signature for TPM is invalid	Invalid TPM signature

Handling Errors in Code

iOS (Swift)

func handleResult(response: String) {
    if let data = response.data(using: .utf8),
       let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any] {
        
        let status = json["status"] as? String ?? ""
        let errorMessage = json["errorMessage"] as? String ?? ""
        let responseCode = json["responseCode"] as? Int ?? 0
        
        if status == "ok" {
            // Success
        } else {
            // Handle error based on responseCode and errorMessage
            switch responseCode {
            case 600...617:
                // Card error - prompt user to tap card again
                break
            case 401:
                // Unauthorized - check credentials
                break
            case 408:
                // Session expired - restart flow
                break
            default:
                // Other error
                break
            }
        }
    }
}

Android (Java)

@Override
public void registerResult(String response) {
    runOnUiThread(() -> {
        try {
            JSONObject json = new JSONObject(response);
            String status = json.optString("status", "");
            String errorMessage = json.optString("errorMessage", "");
            int responseCode = json.optInt("responseCode", 0);
            
            if ("ok".equals(status)) {
                // Success
            } else {
                // Handle error based on responseCode
                if (responseCode >= 600 && responseCode <= 617) {
                    // Card error - prompt user to tap card again
                } else if (responseCode == 401) {
                    // Unauthorized
                } else if (responseCode == 408) {
                    // Session expired
                }
            }
        } catch (JSONException e) {
            e.printStackTrace();
        }
    });
}

Common Error Scenarios

Registration Errors

Scenario	Typical Error	User Message	Recovery Steps
Card pulled away too soon	600, 616, 617	"Hold your card steady and try again"	1. Keep card on device until operation completes 2. Wait for success/failure message
PIN not set	608, 611	"Please set a PIN first"	1. Call setPin() with 6+ digit PIN 2. Retry registration
User already registered	E2019R	"This account is already registered"	1. Use authenticateUser() instead 2. Or re-register with different username
Session timeout	E0024R, E0027R	"Request timed out. Please try again"	1. Restart registration from beginning 2. Ensure network is stable
Invalid relying party	E0025R, E2007R	"Configuration error"	1. Verify RP ID matches server domain 2. Check multi-tenant config
User verification required	E2009R	"Verification required"	1. Ensure PIN is provided 2. Check server UV requirements
Counter error	E2018R	"Security alert: Contact support"	1. May indicate cloned card 2. Re-register with new credential

Authentication Errors

Scenario	Typical Error	User Message	Recovery Steps
User not found	403, E2019R	"Account not found. Please register"	1. Complete registration first 2. Check username spelling
Wrong PIN	608	"Invalid PIN. Please try again"	1. Re-enter PIN carefully 2. After 3 failures, card may lock
Card not registered	602, 603	"Card not registered. Please set up"	1. Register this card for the user 2. Verify correct card is being used
Session timeout	E0027R, 408	"Session expired. Please try again"	1. Restart authentication flow 2. Increase session timeout if frequent
Signature mismatch	E2017R	"Authentication failed. Try again"	1. Retry operation 2. If persistent, re-register card
User verification required	E2016R	"Verification required"	1. Ensure PIN is provided 2. Check server UV requirements
Counter error	E2018R	"Security alert: Contact support"	1. May indicate cloned authenticator 2. Re-register credential
AAGUID not whitelisted	E1045R, E1046R, E1047R	"This authenticator is not allowed"	1. Check AAGUID whitelist config 2. Add AAGUID to whitelist