Skip to main content

​
Overview

TrueParser is an asynchronous parsing platform. Documents are submitted through the API, processed in the background, and made available through status polling and result retrieval. This reliability model is designed to support:
  • asynchronous job execution
  • retry of transient background failures
  • temporary node overload protection
  • durable job-state and artifact handling

​
Asynchronous Processing

When you submit a document, TrueParser accepts the request and queues the parsing job for background processing. What this means for your application:
  • submission does not guarantee immediate parsing completion
  • you should poll the status endpoint for progress
  • you should fetch results only after the job completes

​
Retry Behavior

TrueParser retries certain background processing failures automatically when they are considered transient. Typical retryable conditions may include temporary issues with:
  • infrastructure connectivity
  • storage access
  • network timeouts
  • background processing dependencies
Hard validation or parsing failures are not treated the same way and may result in terminal job failure instead.

​
Overload Protection

TrueParser protects API nodes from overload. If a node becomes overloaded:
  • it may reject non-health API requests with 503 Service Unavailable
  • responses may include Retry-After
  • healthy nodes can continue serving traffic
For routing decisions, the platform exposes a dedicated node-state health endpoint so infrastructure can avoid sending new traffic to overloaded nodes.

​
Health Endpoints

TrueParser provides three important health signals:
  • /health/live
    • confirms the process is alive
  • /health/ready
    • confirms critical dependencies are ready
  • /health/node-state
    • indicates whether the node should continue receiving traffic
For platform routing and overload handling, /health/node-state is the most important endpoint.

​
Job Safety

To prevent duplicate processing and preserve job consistency, TrueParser coordinates background work using shared infrastructure. At a high level, the platform maintains:
  • job status tracking
  • work coordination
  • protection against duplicate concurrent processing
This helps ensure that clients see stable job progression from submission to completion or failure.

​
Artifact Reliability

TrueParser stores:
  • raw uploaded artifacts
  • parsed result artifacts
Clients do not fetch parsed results directly from object storage. Instead, they retrieve results through the API once processing is complete. This keeps access control, result availability, and retrieval behavior consistent.

​
What Clients Should Expect

Clients should design for:
  • asynchronous completion
  • status polling
  • eventual success or failure
  • temporary 503 responses during overload
  • temporary 202 responses from result retrieval while processing is still underway
Clients should not assume:
  • immediate synchronous parsing completion
  • direct object-storage access for result retrieval
  • that every failure is permanent

​
Best Practice

For reliable client behavior:
  1. submit the document
  2. store the returned document id
  3. poll status with backoff
  4. fetch results only after completion
  5. retry 429 and retryable 503 responses with backoff
Last modified on April 1, 2026