> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thewo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage and quotas

> Understand Trade Document usage units, quota checks, and idempotent retries.

# Usage and quotas

Trade Document usage is associated with the `document_extraction` operation.
Each successfully completed extraction records one unit:

```json theme={"theme":"github-dark-default"}
{ "operation": "document_extraction", "units": 1 }
```

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](https://docs.thewo.io/trade-document/guides/product-access.md).

## 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](https://docs.thewo.io/trade-document/guides/errors.md).

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.