Refusals and execution errors
Find all six refusal codes, diagnose failed documents, and design retry and review behavior for reliable financial imports.
A refusal is a completed document decision with status: "refused", data: null, and a machine-readable code. An execution failure interrupts the job before it can produce a decision for one or more inputs. In a batch, keep decisions already returned and track the remaining files as incomplete.
Refusal codes
| Code | Meaning | What to verify |
|---|---|---|
UNKNOWN_LAYOUT | No known layout matched, a required provider is missing, or a restricted npm runner withheld the layout. | Check the source export, the wrapper's LAYOUTS and the installed providers. |
UNSUPPORTED_INPUT | Type, size, encoding or document structure falls outside supported inputs. | Verify the extension and size, whether the PDF is locked, and whether OCR is available. |
PARSE_ERROR | The engine could not read or interpret a required field. | Check the opening balance, date order, currency and the field named in the message. Inspect error.internal for unexpected failures. |
BALANCE_MISMATCH | A reconciliation assertion failed or there was insufficient independent evidence. | Compare printed running balances and totals against the original. Check for missing rows and truncated exports. |
LOW_CONFIDENCE | The OCR or model-assisted reading could not be supported with enough confidence. | Review scan quality, orientation, column labels and source values. |
OUTPUT_INVALID | The result failed contract validation or a required output check could not run. | Record the engine version and diagnose the provider or report a minimal synthetic reproduction. |
Build a retry policy
- Record the outcome. Save the input hash if available, the engine version, supplied parameters, and the refusal or execution error.
- Read the message. A missing opening balance can be corrected with a verified source amount. A layout or reconciliation problem usually needs the document or its export reviewed. Send an
error.internalrefusal for engine diagnosis. - Retry where appropriate. Retry an interrupted file after checking the service. For a refusal, rerun when you can supply verified context or a corrected export.
- Review the new decision. Keep both attempts in history and send only released records onward.
Follow an example
The bank CSV quickstart returns PARSE_ERROR on the first run because the sample has no opening balance. Supplying its known opening balance of INR 1000.00 lets the engine check the two movements against the running balances. The result changes to a release. A wrong opening balance can still fail reconciliation.
Find the outcome in your integration
| Entry point | Where to look |
|---|---|
| CLI | Read the exit code and inspect each written decision. |
| Python | Inspect the returned document and handle engine exceptions when using strict mode. |
| Node.js | Branch on result.kind and catch thrown EngineError values. |
| HTTP API | Read each file.done decision and use run.done to confirm batch completion. |
| MCP | Read the document outcome and check each step for operation errors. |
JSON output contract
Integrate the openbooks.v1 release and refusal contract with exact decimal money, source evidence and verification assertions.
Test a document integration
Verify release and refusal paths, use bundled fixtures for multiple layouts, and check retries and evidence before scheduling imports.