# Refusals and execution errors

Find all six refusal codes, diagnose failed documents, and design retry and review behavior for reliable financial imports.

Source: https://openbooks.lumeo.co.in/docs/refusals

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 [#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 [#build-a-retry-policy]

1. **Record the outcome.** Save the input hash if available, the engine version, supplied parameters, and the refusal or execution error.
2. **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.internal` refusal for engine diagnosis.
3. **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.
4. **Review the new decision.** Keep both attempts in history and send only released records onward.

## Follow an example [#follow-an-example]

The [bank CSV quickstart](/docs/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 [#find-the-outcome-in-your-integration]

| Entry point | Where to look |
| --- | --- |
| [CLI](/docs/cli) | Read the exit code and inspect each written decision. |
| [Python](/docs/python) | Inspect the returned document and handle engine exceptions when using strict mode. |
| [Node.js](/docs/node) | Branch on `result.kind` and catch thrown `EngineError` values. |
| [HTTP API](/docs/engine-api) | Read each `file.done` decision and use `run.done` to confirm batch completion. |
| [MCP](/docs/mcp) | Read the document outcome and check each step for operation errors. |
