Skip to main content

​
Usage and quotas

Trade Document usage is associated with the document_extraction operation. Each successfully completed extraction records one unit:
Access entitlement, rate limits, and commercial quota are separate checks. A valid API key does not grant entitlement, and a customer with entitlement can still exhaust the quota available for its current plan period. Trade Document is currently Coming Soon with no public plan; docs do not grant access. See product access.

​
Quota and failures

Quota is reserved before retrieving the remote source or invoking extraction. Quota exhaustion returns 429 quota_exceeded before the document is fetched. The current private beta plan is configured for 100 successful extractions per subscription period. It remains private and unavailable for self-service activation; actual access and limits depend on the active entitlement. Source rejection or unavailability, unsupported media or document type, oversized content, extraction failure, and persistence failure occur before usage recording. The API attempts to release the quota reservation for failures during execution. A release failure is reported as 503 quota_release_failed. If usage recording itself fails, the API returns 503 usage_recording_failed and attempts to release the reservation. The recorder’s failed result means no successful usage record was confirmed. One exception matters when interpreting a 503: quota_confirmation_failed means the extraction result was persisted and its usage was already recorded, but quota confirmation failed. The error message says this explicitly. With an idempotency key, the committed result can be replayed after the temporary issue is resolved.

​
Idempotency

Idempotency-Key is optional. Without it, a repeated request can execute and record another extraction. With it, the key is scoped to the authenticated customer, Trade Document product, and extraction operation. The request fingerprint includes documentUrl, expectedType when supplied, and language when supplied.
  • Same key and same request after success: the API returns the original result without fetching or extracting again or recording a second usage unit.
  • Same key with a different request: 409 idempotency_conflict.
  • Same key and same request while the first request is running: 409 idempotency_in_progress.
  • A blank, repeated, or longer than 255-character header: 400 invalid_idempotency_key.
  • Temporary idempotency service or replay restoration failure returns a 503 error listed in Errors.
If execution fails before a completed operation is committed, its reservation is released and the key can be retried. Keep a key stable when retrying the same logical request; use a new key when the request changes.

​
Rate limits

The technical request rate is configured for the runtime and is distinct from commercial quota. 429 rate_limit_exceeded indicates the configured request rate was exceeded; follow Retry-After when the response includes it. A temporary rate-limit service failure returns 503 rate_limit_unavailable. The numeric rate is not a stable public value.