Exceptions & error codes

The exception hierarchy is per PEP 249. All exceptions live in informix_db and inherit from informix_db.Error.

Hierarchy

Error
├── Warning
└── DatabaseError
    ├── InterfaceError
    ├── DataError
    ├── OperationalError
    │   └── PoolTimeout
    ├── IntegrityError
    ├── InternalError
    ├── ProgrammingError
    └── NotSupportedError

When each is raised

Exception	Typical cause
InterfaceError	Misuse of the driver API itself (e.g. fetch on a closed cursor).
DataError	Type conversion failures, codec errors.
OperationalError	Network errors, timeouts, server unavailable, login failures.
IntegrityError	Constraint violations (PK, FK, unique, NOT NULL).
InternalError	Driver-internal invariant violation (file a bug).
ProgrammingError	Bad SQL syntax, missing tables, parameter binding errors.
NotSupportedError	Driver doesn’t support the requested operation.
PoolTimeout	Pool acquire exceeded acquire_timeout.

SQLCODE mapping

Informix returns SQLCODE values; the driver maps them to the appropriate exception. A few common ones:

SQLCODE	Meaning	Exception
-201	Syntax error	ProgrammingError
-206	Table not found	ProgrammingError
-239 / -268 / -691 / -703	Unique / FK / NOT NULL violation	IntegrityError
-329	Database not found	OperationalError
-908	Connection terminated by server	OperationalError
-1820	Codeset conversion failure	DataError
-908 / network errors	Server unavailable	OperationalError

The full mapping lives in src/informix_db/_errcodes.py.

Inspecting errors

Every exception carries the original SQLCODE and message:

try:
    cur.execute("INSERT INTO users VALUES (?, ?)", (1, "alice"))
except informix_db.IntegrityError as e:
    print(e.sqlcode)   # -239 (unique violation)
    print(e.isam_code) # secondary error code
    print(str(e))      # human-readable

sqlcode is the primary error; isam_code is the underlying ISAM error (when applicable). For multi-statement transactions, use e.statement to see which statement failed.