Error Codes

Error Code Categories

SoftSDC uses a 4-digit error code system where the first digit indicates the severity:

0xxx - Information codes (successful operations)
1xxx - Warning codes (system continues to work but attention needed)
2xxx - Error codes (operation failed, action required)

Information Codes (0xxx)

These codes indicate successful operations or status information.

Code	Description	Meaning
0000	All OK	Command is executed without warnings or errors
0100	Pin OK	This code indicates that the provided PIN code is correct
0210	Internet Available	Internet Connection is available (optional)
0220	Internet Unavailable	Internet Connection is not available (optional)

Warning Codes (1xxx)

These warnings indicate potential issues that don't prevent operation but require attention.

Code	Description	Impact	Action Required
1100	Storage 90% Full	Storage used to store audit packages is 90% full	Perform audit soon to free space
1300	Smart Card Not Present	Secure element card is not inserted in the E-SDC smart card reader	Insert smart card to continue
1400	Audit Required	Total Sale and Refund amount reached 75% of the SE limit	Perform audit to continue operations
1500	PIN Code Required	Indicates that POS must provide the PIN code	Submit PIN via /api/v3/pin endpoint
1999	Undefined Warning	Something is wrong but specific warning is not defined	Check message field for details. Manufacturer may use specific codes

1100 and 1400 warnings indicate that an audit will soon be required. Plan accordingly to avoid service interruption.

Error Codes (2xxx)

These errors indicate operation failures that require immediate attention.

Authentication Errors (21xx)

Code	Description	Details	Resolution
2100	Pin Not OK	PIN code sent by the POS is invalid	Verify PIN and retry. Check remaining attempts
2110	Card Locked	The number of allowed PIN entries exceeded	Card is locked. Contact Tax Authority to reset

2110 - Card Locked: This is a critical error. The smart card cannot be used until it's reset by the Tax Authority. Never share your PIN or allow unauthorized access to prevent this situation.

Secure Element Errors (22xx)

Code	Description	Details	Resolution
2210	SE Locked	Secure Element is locked	No additional invoices can be signed before audit is completed. Perform audit immediately
2220	SE Communication Failed	E-SDC cannot connect to the Secure Element applet	Check smart card connection. Try removing and reinserting card. Restart service if needed
2230	SE Protocol Mismatch	Secure Element does not support requested protocol version	Update software or contact support (reserved for later use)

Configuration Errors (23xx-24xx)

Code	Description	Details	Resolution
2310	Invalid Tax Labels	Tax Labels sent by the POS are not defined	Verify tax labels match configured tax rates. Check /api/v3/status for valid labels
2400	Not Configured	SDC device is not fully configured for invoice signing	Run initialization. Tax rates or verification URL may be missing

Validation Errors (28xx)

These errors indicate problems with the data submitted in API requests.

Code	Description	Details
2800	Field Required	A mandatory invoice request field is missing
2801	Field Value Too Long	The length of the field value exceeds maximum allowed
2802	Field Value Too Short	The length of the field value is less than minimum required
2803	Invalid Field Length	The field value length doesn't match expected length
2804	Field Out Of Range	A field value is outside the expected range
2805	Invalid Field Value	A field contains an invalid or malformed value
2806	Invalid Data Format	The data format is invalid (e.g., non-ASCII digits in PIN)
2807	List Too Short	The list of items or tax labels doesn't contain at least one element
2808	List Too Long	The list exceeds maximum allowed number of elements or byte size
2809	Secure Element Expired	The digital certificate on the smart card has expired

Validation Errors (28xx): These are typically caused by incorrect data in your API requests. Review the request payload and ensure all fields meet the requirements specified in the API documentation.

Error Handling Best Practices

Critical Errors (Immediate Action Required)

const CRITICAL_ERRORS = ['2110', '2210', '2809'];

function handleResponse(code, message) {
  if (CRITICAL_ERRORS.includes(code)) {
    // Stop operations immediately
    // Alert system administrator
    // Log detailed error information
    notifyAdministrator(code, message);
    disableFiscalization();
  }
}

Recoverable Errors (Retry Logic)

const RECOVERABLE_ERRORS = ['2220', '1300'];

async function createInvoiceWithRetry(invoice, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const result = await createInvoice(invoice);

    if (result.code === '0000') {
      return result;
    }

    if (RECOVERABLE_ERRORS.includes(result.code)) {
      await sleep(2000 * (i + 1)); // Progressive delay
      continue;
    }

    throw new Error(`Unrecoverable error: ${result.code}`);
  }

  throw new Error('Max retries exceeded');
}

Warning Handling

const WARNING_CODES = ['1100', '1400'];

function checkWarnings(status) {
  const warnings = status.gsc.filter(code =>
    WARNING_CODES.includes(code)
  );

  if (warnings.includes('1100')) {
    scheduleAudit('soon'); // Within 24 hours
  }

  if (warnings.includes('1400')) {
    scheduleAudit('urgent'); // As soon as possible
  }
}

Status Code Examples

Successful Operation

{
  "gsc": ["0100"],
  "mssc": [],
  "messages": "Success"
}

Multiple Status Codes

{
  "gsc": ["0100", "0220"],
  "mssc": ["1400"],
  "messages": "PIN verified. Internet unavailable. Audit recommended."
}

Error Response

{
  "gsc": ["2100"],
  "mssc": [],
  "messages": "PIN verification failed. 3 attempts remaining."
}

Manufacturer-Specific Codes (6xxx)

Codes starting with 6 are manufacturer-specific and may provide additional detail about system status:

Code	Description
6001	Manufacturer-specific info
6xxx	Reserved for manufacturer extensions

Manufacturer-specific codes provide additional context but should not be used for critical decision-making in integrations. Always rely on standard error codes for operational logic.

Debugging Tips

Enable Verbose Logging

When troubleshooting errors:

Enable detailed logging in Settings
Review application logs for context
Check timestamp sequence for timing issues
Verify network connectivity for connection errors

Common Error Scenarios

Scenario: PIN Errors (2100, 2110)

Symptoms: Cannot authenticate with smart card

Checklist:

Verify PIN is correct
Check how many attempts remain
Ensure card is properly inserted
Verify card reader is functioning

Scenario: Validation Errors (28xx)

Symptoms: Invoice creation fails

Checklist:

Validate all required fields are present
Check field value formats (dates, numbers)
Verify tax labels match current rates
Ensure item array is not empty

Scenario: Communication Errors (2220)

Symptoms: Cannot connect to secure element

Checklist:

Check smart card is inserted correctly
Try removing and reinserting card
Restart SoftSDC service
Test with different USB port
Verify card reader drivers are installed

Error Response Format

All error responses include:

{
  "gsc": ["2100"],           // General Status Codes
  "mssc": [],                // Manufacturer-Specific Status Codes
  "messages": "Description", // Human-readable message
  "details": "..."           // Additional context (optional)
}

For complete API response examples, see the API Reference documentation.

Error Codes

On this page