How to build document extraction pipelines that handle failures, retries, queue backlogs, and partial outputs reliably using ADE reliability primitives.
Production document pipelines encounter transient failures, rate limit responses, and unexpected document formats at volume; a pipeline that surfaces these failures to the calling application cannot operate reliably at scale. ADE provides the reliability primitives that make fault-tolerant design achievable: built-in retry handling, async job monitoring, durable job IDs, and explicit error signals for non-retriable failures.
Built-In Retry Handling
The Python library implements exponential backoff with randomised jitter on transient error codes (408, 429, 502, 503, 504), retrying failed requests without surfacing transient failures to the calling application. Pipelines using the REST API directly must implement retry logic themselves using the same five transient error codes.
The critical fault-tolerance distinction is between transient errors (retry with backoff) and terminal errors (route to dead-letter queue): 400 Bad Request, 401 Unauthorized, and 413 Payload Too Large are terminal and should not be retried without intervention. See rate limits documentation for current limits by plan tier.
Durable Job Tracking with Parse Jobs
The Parse Jobs API processes large documents asynchronously and returns a job_id immediately on submission. Storing job_id values durably in a database or queue is the single most important fault-tolerance decision for batch pipelines: a pipeline that loses job IDs on restart cannot recover in-flight work without re-submitting documents and consuming additional credits.
The List Parse Jobs endpoint returns all jobs associated with an API key, supporting backlog assessment and stuck-job detection without relying on in-memory state.
Handling Partial and Failed Outputs
When extraction returns null fields or low-confidence values, the pipeline needs a decision path that does not block the main flow:
- High confidence. Field passes to the downstream system with bounding-box citation stored for audit.
- Low confidence. Field routes to a review queue with the source location pre-populated from the confidence score and bounding-box citation.
- Null return. Field absent from the document; treated as a missing-data flag triggering a separate workflow branch.
- Terminal error. Document routed to a dead-letter queue with the error code and document reference.
Treating null returns and terminal errors as distinct signals rather than collapsing both into "failure" is what separates a fault-tolerant design from one requiring manual intervention at volume.
ZDR Constraints in Fault-Tolerant Pipelines
Parse Jobs with Zero Data Retention enabled write parsed results to a customer-provided presigned URL in customer-controlled storage, and the presigned URL must be generated before job submission and stored in the job registry alongside the job_id. Presigned URLs have expiry times; fault-tolerant ZDR pipelines generate presigned URLs with expiry times that exceed the expected maximum processing time for the document.
FAQ
What is the minimum retry implementation for a pipeline calling the ADE REST API directly? Retry on error codes 408, 429, 502, 503, and 504 with exponential backoff and randomised jitter, and add a maximum retry count with a dead-letter queue to prevent indefinite loops. Do not retry on 400, 401, or 413 without operator intervention; the Python library implements this pattern automatically for Python pipelines.
How should a batch pipeline recover from a restart without re-submitting all documents? Store each job_id durably immediately after submission alongside the document reference and submission timestamp. On restart, query the List Parse Jobs endpoint to recover in-flight job statuses and resume polling from the durable registry.
How does the pipeline detect and handle stuck jobs? Set a timeout threshold in the job registry based on expected processing time for the document size, and alert when a job exceeds that threshold. The List Parse Jobs endpoint provides job status across all in-flight jobs without relying on per-job polling.
What is the correct pattern for terminal errors at high volume? Route documents that return 400, 401, or 413 to a dead-letter queue immediately with the error code and document reference, and alert operators with sufficient context to diagnose the failure. A 413 document needs to be split or resized; a 400 requires code-level investigation.
Does fault-tolerant pipeline design require an Enterprise plan? No. The retry handling in the Python library, the Parse Jobs API, and the List Parse Jobs endpoint are available across all plan tiers.
Enterprise plans provide customisable rate limits and SLA commitments relevant for sizing throughput headroom; see rate limits documentation.