Skip to main content

​
Overview

TrueParser returns standard HTTP status codes together with JSON error bodies for most API failures. The most common error payload shape is: 
{
  "error": "error_code",
  "message": "Human-readable explanation"
}
Some endpoints may also return route-specific fields such as detail.

​
Authentication Errors

These errors happen when a request is missing a valid access token or the token does not satisfy API policy.
HTTP StatusError CodeMeaning
401missing_tokenNo bearer token was provided.
401token_expiredThe access token has expired.
401invalid_tokenThe token could not be accepted.
403invalid_scopeThe token does not have the required API scope.
403domain_not_allowedThe request origin is not allowed for this application.
503auth_unavailableAuthentication infrastructure was temporarily unavailable.

​
Document Submission Errors

These errors happen during document ingestion.
HTTP StatusError CodeMeaning
400invalid_inputThe uploaded file is missing or empty.
400document_type_requiredZIP uploads must include an explicit documentType.
400unsupported_formatThe file format is not supported.
400csv_route_requiredCSV uploads must include csvRoute.
400sql_dialect_requiredSQL uploads must include sqlDialect.
400pdf_mode_requiredPDF uploads must include pdfMode.
400invalid_metadatacustomMetadataJson is not valid JSON.
403advanced_extraction_not_allowedThe current plan does not allow advanced PDF extraction.
403license_restrictionThe requested operation is not allowed under the current plan or format entitlement.
413document_too_largeThe upload exceeds the maximum allowed size for the plan.
429rate_limit_exceededThe application exceeded its API traffic limit.
429quota_exceededThe application exceeded a quota window and cannot accept more work right now.
503none fixedThe node is temporarily overloaded.

​
Result and Status Errors

These errors happen when checking status or retrieving parsed results.
HTTP StatusError CodeMeaning
404not_foundNo job exists for the requested document id.
404result_not_foundThe job completed but no result reference was available.
404document_expiredThe parsed result is no longer available.
422extraction_failedThe parser failed to process the document.
202none fixedThe job is still processing and the result is not ready yet.

​
Health and Overload Responses

TrueParser also exposes health and overload signals:
EndpointHTTP StatusMeaning
/health/live200The service process is alive.
/health/ready503A required dependency is not ready.
/health/node-state503The node is overloaded and should not receive new traffic.
When a node is overloaded, the API may return a response like: 
{
  "status": 503,
  "state": "overloaded",
  "reason": "cpu",
  "retryAfter": 60
}

​
Quota and Processing Failures

Background processing failures may eventually surface through status polling or result retrieval. Common examples include:
  • quota_exceeded
  • document_quota_exceeded
  • job_timeout
  • processing_failed
  • transient_infrastructure_failure

​
What Clients Should Do

  • treat the HTTP status code as the primary signal
  • inspect the error field when present
  • use retry with backoff for 429 and appropriate 503 responses
  • poll status for asynchronous jobs instead of assuming immediate completion
Last modified on April 1, 2026