Convert a legacy Office archive with checkpoints and quality gates

A production migration should be resumable, observable, and conservative. Inventory files first, assign a stable idempotency key to every source object, limit concurrency, and record the outcome before moving to downstream parsing or storage.

Recommended stages

Inventory. Record source identifier, path, extension, byte size, hash, owner, access scope, and retention class.

Pre-filter. Exclude files over 4 MiB, unsupported extensions, known encrypted content, and anything the organization is not authorized to process.

Submit. Upload each eligible source with an idempotency key derived from a stable internal identifier, not from its filename alone.

Poll. Query each task with bounded backoff until SUCCEEDED, FAILED, or EXPIRED.

Download. Write successful outputs to the customer-controlled destination immediately.

Validate. Run structural checks, format-specific automated checks, and representative visual sampling.

Continue. Only approved outputs move into the archive, migration connector, parser, or AI ingestion pipeline.

Manifest fields

Field	Purpose
`source_id`	Stable identifier independent of the filename
`source_sha256`	Detects source changes and supports audit comparison
`idempotency_key`	Prevents duplicate tasks and duplicate allowance consumption during retries
`task_id`	Links the manifest to the API task
`status` and `error_code`	Separates successful, retryable, and unsupported cases
`result_sha256`	Confirms the downloaded result is stable in customer storage
`validation_state`	Records automated and human quality gates
`destination_uri`	Links to the customer-controlled result location

Idempotency strategy

Use a value that stays stable for the same source version, such as a migration-run identifier plus an immutable source record ID and version. The key must contain 8–128 letters, digits, periods, colons, underscores, or hyphens.

migration-2026-08:records-archive:000042:v3

Reusing that key with identical bytes returns the original task. Reusing it with different bytes returns idempotency_conflict, which protects the manifest from silently pointing at another source version.

Concurrency and polling

Begin with two concurrent submissions and increase gradually while monitoring latency and throttling.
Poll every two to five seconds rather than continuously.
Use exponential backoff with jitter for transport errors and HTTP 503 responses.
Do not retry permanent file errors such as not_ole_cfb, external_workbook_reference, or database_formula.
Checkpoint every state transition so a process restart does not resubmit completed work.

Result validation

A successful API task means the OOXML ZIP opened and contained the required main document part. It does not replace business-specific verification.

Format	Automated checks	Sampling checks
DOCX	ZIP integrity, main Word part, expected paragraph/table counts where known	Page flow, headers, footers, floating objects, fonts
PPTX	ZIP integrity, presentation part, slide count	Slide rendering, text overflow, shapes, charts, fills
XLSX	ZIP integrity, workbook part, sheet count and names	Formulas, cached values, dates, formats, merged cells, borders

Allowance reconciliation

Only successful, structurally validated outputs consume shared allowance. Keep your manifest of successful task IDs and compare it with GET /v1/account/usage. After allowance is exhausted, successful tasks are reported as overage. Authentication failures, failed jobs, task queries, downloads, and idempotent replays are not counted.

AI/RAG handoff

After format and quality validation, hand the OOXML file to the parser stage. Preserve source identity and access-control metadata so extracted elements and vector chunks can always be traced to the authorized source.

Do not make the conversion queue your only source of truth. The client owns its migration manifest, destination storage, access controls, human-review decisions, and retry policy.

Design the downstream AI stage →
Parse and structure results after normalization Classify failures →
Permanent errors versus safe retries