Failures & recovery

Distils saves progress during scientific PDF extraction so an interrupted corpus run can resume from its accepted records. Temporary service errors and unusable model output follow separate recovery rules.

Recovery policy

Connection errors, timeouts, HTTP 408/409/429, and server errors receive up to three retries. Backoff is 2, 4, and 8 seconds, or 30, 60, and 120 seconds for rate limits. Retry-After takes precedence; values above 120 seconds stop the run for later resumption. The SDK adds no retries.

Unusable model output

Malformed lines are discarded with warnings when usable records remain. An unusable response gets one new request with the original prompt and the format error. If it still fails, failed_steps records the gap and processing continues. The command exits 1 after processing the remaining work if any document is incomplete.

Stop and resume

Permanent API errors, refusals, exhausted API retries, GROBID errors, and local I/O failures stop the run and cancel other workers. Unexpected programming errors retain their traceback. Repeat the same runner command after fixing a service problem or interrupting a run. Accepted responses are recovered locally even if their checkpoint write failed.

One process owns a run directory. Resuming requires identical code, inputs, and settings.