Module errors 

One error namespace for the whole C API.

Every negative code a POUNCE extension entry point returns is a POUNCE_ERR_* value from this module, and each value has exactly one meaning wherever it appears: a wrapper can keep a single code-to-message table, and a log line that says -3 means “index out of range” whichever function wrote it. PounceErrorString is that table, so every frontend reports the same text.

The values are grouped in blocks:

block	meaning
-1 … -19	generic: any function may return these
-20 … -39	complementarity pairs (*PounceComplementarityPair*, AddPounceComplementsConstraint)
-40 … -59	bound updates (SetPounceBounds, GetPounceBounds)
-60 … -79	the QP handle (PounceQp*)

A new code is appended inside its block, and a number is never reused or renumbered once released. A new function family gets a new block. A code from one family’s block may be returned by another family when the meaning is the same (POUNCE_ERR_ROW_NOT_FREE is returned by both AddPounceComplementsConstraint and SetPounceBounds).

Every function checks in the same order, so a call with several faults reports the same code whichever function it is:

1. the handle (POUNCE_ERR_NULL);
2. flags and enum arguments (POUNCE_ERR_FLAGS, POUNCE_ERR_ARGUMENT);
3. counts (POUNCE_ERR_COUNT), then the arrays they size (NULL);
4. per entry, over the whole batch in batch order: range, then duplicate or already paired, then NaN;
5. per entry, over the whole batch in batch order: what the entry would mean (shape, row not free, variable bounds, Complements class, pair changed);
6. state beyond the batch (the staged working set; PounceQpSolve’s checks).

An argument fault anywhere in a batch is therefore reported before a semantic fault anywhere in it. tests/check_order.rs holds the batch functions to this.

Non-negative returns stay per function: POUNCE_OK (0) for success, and the QP statuses (POUNCE_QP_STATUS_*) and AddPounceComplementsConstraint outcomes (POUNCE_COMPLEMENTS_*) are results, not errors.

The header (include/pounce.h) repeats every value; tests/header_abi.rs holds the two to the same names and values, and checks that PounceErrorString has a message for each.

Constants

POUNCE_ERROR_CODES

Every code with its message: the single table PounceErrorString reads, and the list tests/header_abi.rs checks the header against.

POUNCE_ERR_ARGUMENT

An argument outside its domain: an unknown enum value (a view, a cone kind), a bad cone dimension or exponent, or entries whose sum overflows.

POUNCE_ERR_COMPLEMENTS_CLASS

A variable used by AddPounceComplementsConstraint would move to another row of the MOI table (lower-only, upper-only, boxed, fixed, free).

POUNCE_ERR_CONES

The cones do not partition the inequality rows, or PSD is mixed with the exponential or power cone.

POUNCE_ERR_COUNT

A count out of range: negative, larger than the dimension it indexes, or inconsistent with a NULL index array.

POUNCE_ERR_DUPLICATE

The same index given twice where each may appear once.

POUNCE_ERR_FLAGS

flags carries a bit this library does not define. An unknown bit is refused, so an older library never silently ignores one.

POUNCE_ERR_INCOMPLETE

The QP is incomplete: no objective, or declared rows never set.

POUNCE_ERR_INDEFINITE

method=ipm and P not certified positive semidefinite.

POUNCE_ERR_INTERNAL

A Rust panic caught at the boundary, or a handle whose stored state no longer validates. Not expected; it exists so neither is reported as a diagnosis of the caller’s input. Nothing was changed.

POUNCE_ERR_NAN

A NaN value where a number is required.

POUNCE_ERR_NULL

A NULL handle, or a NULL array the call needed.

POUNCE_ERR_OPTIONS

An option the selected engine would silently drop.

POUNCE_ERR_OUT_OF_RANGE

An index outside [0, n) / [0, m), read in the problem’s index style.

POUNCE_ERR_PAIR_CHANGED

A declared pair would leave its native shapes, or change which variable bound and which row side it pairs.

POUNCE_ERR_ROW_ALREADY_PAIRED

The row is already in a pair (declared earlier, or earlier in the same batch or an earlier accepted call).

POUNCE_ERR_ROW_NOT_FREE

A row that must stay a free function was given (or has) a finite bound: MOI’s F in AddPounceComplementsConstraint, which SetPounceBounds then refuses to bound.

POUNCE_ERR_SHAPE

The pair’s bounds are none of the lowered shapes: one-sided, one-sided plus a plain bound, or mixed.

POUNCE_ERR_VAR_ALREADY_PAIRED

The variable is already in a pair (declared earlier, or earlier in the same batch or an earlier accepted call).

POUNCE_ERR_VAR_BOUNDS

The variable’s bounds are NaN or crossed (l > u): no row of the MOI complements table applies.

POUNCE_ERR_WORKING_SET

The working set staged by IpoptSetWarmStartWorkingSet would claim something the new bounds contradict.

POUNCE_OK

Success.

Functions

PounceErrorString^⚠

The message for a POUNCE_OK / POUNCE_ERR_* code, as a static NUL-terminated string the caller must not free; "unknown error code" for any other value. Never NULL.