Error Codes

This page is the complete reference of the error codes returned by the FisCool driver, across all interfaces (HTTP, WebSocket, INP execution errors).

Error Response Format

All APIs return errors in a consistent JSON format:

{
  "status": 500,                             // application-specific error code (positive integer)
  "error": "Lipsă hârtie în imprimantă.",    // human-readable message (Romanian)
  "receipt": "..."                           // OPTIONAL: present only on some POS errors
}

• The status field in the body is the application error code documented below; the HTTP status code of the response follows REST conventions (see the mapping on the HTTP API page).
• The optional receipt field appears on POS transaction errors that produced a printable slip (e.g. a declined sale).

Application Errors

Errors raised by the driver itself - before or around device communication.

Fiscal Device Errors (500–599)

Errors reported by the fiscal devices - hardware, state or operational issues. Messages are shown exactly as returned in the error field.

Hardware and State Errors (500–519)

Fiscal Memory and Electronic Journal Errors (520–529)

Operational Errors (530–549)

Command and Syntax Errors (550–559, 599)

POS Terminal Errors (600–611)

Errors specific to POS terminal operations. These may carry the optional receipt field with the terminal slip.

Printer Errors (2001–2005)

Errors from the non-fiscal printing subsystem (/printers/print_html and the WebSocket print action).

Error Handling Best Practices

• Code ranges: categorise by range:
  • 400, 404, 408: request/configuration errors - fix the request
  • 1000–1015: application errors - check the driver/system state
  • 500–599: fiscal device errors - check the device
  • 600–611: POS errors - handle the transaction state
  • 2001–2005: printer errors - check the printer setup
• Retry logic:
  • Transient errors (505, 408, 1004, 1005, 605, 606): safe to retry with backoff - but for POS sales always use an Idempotency-Key so a retry cannot double-charge.
  • State errors (530, 531, 532, 544, 545): fix the device state first, then retry.
  • Configuration errors (400, 404, 540, 1009): do not retry without fixing the request/setup.
• User messaging: the error messages are already user-friendly Romanian text, suitable for direct display.
• Logging: always log both the code and the full message.

Common Error Scenarios

530 (ReceiptOpen)   → cancel/finalise the receipt left open on the device
544 (ZNeeded)       → print the Z report first
400 (Config)        → payments don't match the total, inactive VAT rate, no item lines
1004 (Connection)   → the device is not connected

404 (DeviceNotFound)      → wrong device_id / device deleted
1004 (Connection)         → network/serial connection failed
505 (DeviceBusy)          → device responding but busy - retry
509/508 (GeneralError)    → device reachable but reported an error

600–603 → card/payment problem - customer action required
604     → cancelled - no further action
605–606 → communication problem - check terminal, retry (idempotency!)
609     → settlement failed - check terminal status
Note: the error body may include "receipt" with the decline slip.

Integration Testing

Test your error handling for these critical scenarios:

• Device disconnected mid-operation
• Out-of-paper conditions
• Receipt left open on the device
• POS terminal communication failures and declines
• Z report required
• Licence validation failures