Skip to main content

Resume And Idempotency

Real validation runs create saved validation state next to the input CSV so interrupted runs can resume without starting duplicate API work.

State File​

For:

customers.csv

The CLI writes:

customers.csv.optimus-state.json

The state file stores:

  • Request hash.
  • Idempotency key.
  • Operation ID when available.
  • Operation status.
  • Timestamps.
  • API base URL.
  • Result path.
  • PDF path.
  • Support log path.
  • Last general operation error when one occurs.

The state file does not store tokens.

Automatic Resume​

When the same file is processed again with the same relevant request options and API target, the CLI uses the saved state.

In a non-interactive terminal, the CLI resumes automatically.

In an interactive terminal, the CLI can ask whether to resume or start a new operation.

Start A New Operation​

Use --force-new to ignore saved state and start a new validation operation:

optimus check customers.csv --map mapping.yml --standard --force-new

When --force-new is used, the CLI creates a new idempotency key by appending a unique suffix.

Idempotency Keys​

The CLI generates idempotency keys automatically from the validation request. Users do not need to create or pass these keys.

This keeps retries and resume behavior tied to the exact CSV data, mapping, API target, and validation options used for the run. Folder mode generates one idempotency key per CSV file.

When State Is Replaced​

The CLI starts a new operation when:

  • --force-new is passed.
  • The saved operation has expired.
  • The saved operation is no longer available from the API.
  • An interactive user confirms replacement for corrupt or mismatched state.

If corrupt or mismatched state is found in a non-interactive run, the CLI reports an error and tells you to use --force-new.