Errors and diagnostics

This page describes how errors are reported in Python and the C API.

Quick summary:

Python raises RuntimeError on failures.
C APIs return a sqzc3d_STATUS_* code; use sqzc3d_last_error(...) for a human message.
If a build lacks a capability, you may see sqzc3d_STATUS_NOT_IMPLEMENTED.

Mental model: treat errors as “actionable messages”, not silent fallbacks.

Python

Python bindings raise RuntimeError on failures.

Example:

import sqzc3d

try:
    v = sqzc3d.read("missing.c3d")
except RuntimeError as e:
    print("failed:", e)

Feature discovery:

import sqzc3d

features = sqzc3d.features()
print("features=", features)

If a build is missing a capability, APIs may fail with sqzc3d_STATUS_NOT_IMPLEMENTED (surfaced as an exception in Python).

C API

Most APIs return a sqzc3d_STATUS_* code (see sqzc3d_types.h).

When a call fails, use:

sqzc3d_last_error(dec) to get a human-readable message
sqzc3d_last_error(NULL) for errors that happen before a decoder handle exists (e.g. open failure)

Example:

sqzc3d_dec_t* dec = NULL;
int st = sqzc3d_open_file(&dec, path, &open_opt);
if (st != sqzc3d_STATUS_SUCCESS) {
  fprintf(stderr, "open failed: %s\n", sqzc3d_last_error(NULL));
  return 1;
}

Structured details (optional):

sqzc3d_last_error_detail(dec, &detail)