Error Reference

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.

These errors happen when a request is missing a valid access token or the token does not satisfy API policy.

HTTP Status	Error Code	Meaning
`401`	`missing_token`	No bearer token was provided.
`401`	`token_expired`	The access token has expired.
`401`	`invalid_token`	The token could not be accepted.
`403`	`invalid_scope`	The token does not have the required API scope.
`403`	`domain_not_allowed`	The request origin is not allowed for this application.
`503`	`auth_unavailable`	Authentication infrastructure was temporarily unavailable.

These errors happen during document ingestion.

HTTP Status	Error Code	Meaning
`400`	`invalid_input`	The uploaded file is missing or empty.
`400`	`document_type_required`	ZIP uploads must include an explicit `documentType`.
`400`	`unsupported_format`	The file format is not supported.
`400`	`csv_route_required`	CSV uploads must include `csvRoute`.
`400`	`sql_dialect_required`	SQL uploads must include `sqlDialect`.
`400`	`pdf_mode_required`	PDF uploads must include `pdfMode`.
`400`	`invalid_metadata`	`customMetadataJson` is not valid JSON.
`403`	`advanced_extraction_not_allowed`	The current plan does not allow advanced PDF extraction.
`403`	`license_restriction`	The requested operation is not allowed under the current plan or format entitlement.
`413`	`document_too_large`	The upload exceeds the maximum allowed size for the plan.
`429`	`rate_limit_exceeded`	The application exceeded its API traffic limit.
`429`	`quota_exceeded`	The application exceeded a quota window and cannot accept more work right now.
`503`	none fixed	The node is temporarily overloaded.

These errors happen when checking status or retrieving parsed results.

HTTP Status	Error Code	Meaning
`404`	`not_found`	No job exists for the requested document id.
`404`	`result_not_found`	The job completed but no result reference was available.
`404`	`document_expired`	The parsed result is no longer available.
`422`	`extraction_failed`	The parser failed to process the document.
`202`	none fixed	The job is still processing and the result is not ready yet.

TrueParser also exposes health and overload signals:

Endpoint	HTTP Status	Meaning
`/health/live`	`200`	The service process is alive.
`/health/ready`	`503`	A required dependency is not ready.
`/health/node-state`	`503`	The 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
}

Background processing failures may eventually surface through status polling or result retrieval. Common examples include: