> ## 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.

# Errors

> Trade Document HTTP status codes, public error codes, and retry guidance.

# Errors

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

```json theme={"theme":"github-dark-default"}
{
  "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](https://docs.thewo.io/trade-document/guides/usage-and-quotas.md#idempotency).


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