Errors

Trade Document uses The Wo’s shared JSON error envelope:

{
  "error": {
    "code": "invalid_request_payload",
    "message": "Request body does not match the document extraction contract.",
    "requestId": "req_123"
  }
}

Some errors include safe structured details. Keep requestId when reporting an issue. The API does not return credentials, stack traces, provider secrets, or private implementation errors in this envelope.

Public errors

HTTP	Code	Meaning
400	`invalid_json`	Request body contains malformed JSON.
400	`invalid_request_payload`	JSON does not match the strict request schema.
400	`invalid_idempotency_key`	Header is blank, contains multiple values, or is longer than 255 characters.
401	`missing_api_key`	`x-api-key` was not provided.
401	`invalid_api_key`	Credential is invalid, inactive, or revoked.
403	`customer_access_denied`	Authenticated customer access is denied.
403	`product_not_entitled`	Customer has no Trade Document entitlement.
403	`quota_access_denied`	Customer cannot access the requested extraction quota.
409	`idempotency_conflict`	Key was used with a different request.
409	`idempotency_in_progress`	The same keyed request is still being processed.
413	`document_too_large`	Retrieved content exceeds the deployment’s configured size limit.
415	`unsupported_document_media`	Retrieved content type is not PDF, JPEG, PNG, or WebP.
422	`invalid_document_request`	Application-level extraction request validation failed.
422	`document_source_rejected`	Source URL or target was rejected by remote-resource safety checks.
422	`unsupported_document`	Content is not a supported invoice or receipt.
429	`rate_limit_exceeded`	Configured technical request rate was exceeded. Follow `Retry-After` when present.
429	`quota_exceeded`	Current commercial operation quota is exhausted.
500	`internal_error`	An unexpected error occurred.
502	`extraction_failed`	Document extraction failed.
502	`invalid_extraction_output`	Extractor output could not be represented by the public contract.
503	`api_key_authentication_unavailable`	API key could not be safely validated.
503	`entitlement_check_unavailable`	Product entitlement cannot currently be evaluated.
503	`idempotency_unavailable`	Idempotency service is unavailable.
503	`idempotency_replay_unavailable`	Original result cannot currently be restored.
503	`quota_check_unavailable`	Quota could not be checked.
503	`quota_confirmation_failed`	Usage was recorded, but quota confirmation failed.
503	`quota_release_failed`	The extraction reservation could not be released.
503	`document_source_unavailable`	Remote source could not be reached.
503	`extraction_unavailable`	Extraction service is temporarily unavailable.
503	`trade_document_persistence_failed`	Extraction result could not be stored.
503	`usage_recording_failed`	Extraction usage could not be recorded.
503	`rate_limit_unavailable`	Rate-limit evaluation is temporarily unavailable.

Retry guidance

Correct request or authentication errors before retrying. For 429 rate_limit_exceeded, wait for the Retry-After duration when supplied. For 429 quota_exceeded, wait until quota is available or access changes. Temporary 503 failures may be retried using your normal bounded backoff policy. Use the same Idempotency-Key for a retry of the same logical request so a completed result is not extracted and charged twice. quota_confirmation_failed is a special case: its public message states that usage was already recorded. See Usage and quotas.

Overview

Getting started

Product guides

Examples

Errors

Errors

Public errors

Retry guidance

​Errors

​Public errors

​Retry guidance

Errors

Public errors

Retry guidance