Error Codes

This section provides a comprehensive reference of all error codes that can be returned by the FisCool driver. Understanding these codes is crucial for building robust integrations and implementing proper error handling.

Error Response Format

All APIs return errors in a consistent JSON format:

{
  "status": 500,                    // Application-specific error code
  "error": "Lipsă hârtie în imprimantă."  // User-friendly error message (usually Romanian)
}

Note: HTTP status codes in response headers follow REST conventions, while the status field in the JSON body provides application-specific error classification.

Application Errors (1000-1999)

These errors occur at the application level, before device communication or during internal processing.

Fiscal Device Errors (500-599)

These errors are reported by fiscal devices and represent hardware, state, or operational issues.

Hardware and State Errors (500-519)

Fiscal Memory and Electronic Journal Errors (520-529)

Operational Errors (530-549)

Command and Syntax Errors (550-559)

POS Terminal Errors (600-619)

These errors are specific to POS terminal operations and card processing.

Printer Errors (2000-2999)

These errors occur when using the printing subsystem for non-fiscal printing operations.

Error Handling Best Practices

For Application Developers

• Status Code Ranges: Use error code ranges to categorize error types:
  • 400, 404: Client/configuration errors - fix request
  • 1000-1999: Application errors - check system state
  • 500-599: Device errors - check device status
  • 600-619: POS errors - handle transaction state
  • 2000+: Printer errors - check printer setup
• Retry Logic: Implement appropriate retry logic:
  • Temporary errors (505, 1004, 1005): Safe to retry with backoff
  • State errors (530, 531, 532): Fix state before retry
  • Configuration errors (400, 404, 1008): Don't retry without fixing issue
• User Messaging: Use the Romanian error messages for end-user display
• Logging: Always log both the error code and full error context

Common Error Scenarios

// Check device state before starting
GET /devices/{device_id}

// Common sequence errors:
530 (ReceiptOpen) → Cancel existing receipt first
531 (ReceiptNotOpen) → Initialize receipt before adding items
537 (InvalidAmount) → Validate amounts are > 0
544 (ZNeeded) → Print Z report before continuing

// Connection error progression:
404 (DeviceNotFound) → Device not configured
1004 (Connection) → Network/serial connection failed
505 (DeviceBusy) → Device responding but busy
508 (GeneralDeviceError) → Device communication established but error occurred

// POS error handling:
600-603 → Card/payment issue - customer action required
604 → Transaction cancelled - no further action needed
605-606 → Communication issue - retry possible
609 → Settlement failed - check terminal status

Integration Testing

Test error handling for these critical scenarios:

• Device disconnection during operation
• Paper out conditions
• Invalid receipt sequences
• POS terminal communication failures
• Z report requirements
• License validation failures