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

> ClaimReady HTTP statuses, public error codes, and retry guidance.

# Errors

ClaimReady 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 ClaimReady triage contract.",
    "requestId": "req_123"
  }
}
```

Some errors include safe `details`. Keep `requestId` when reporting an issue.
The envelope does not expose credentials, stack traces, provider secrets, or
private implementation details.

## POST errors

| HTTP | Code | Meaning |
| -: | - | - |
| 400 | `invalid_json` | Request body is not valid JSON. |
| 400 | `invalid_request_payload` | Body does not match the strict schema or contains an unknown domain. |
| 400 | `invalid_idempotency_key` | Required key is blank or exceeds 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 active ClaimReady entitlement. |
| 500 | `request_context_unavailable` | Authenticated request context could not be read. |
| 409 | `idempotency_conflict` | Key was used with materially different input. |
| 409 | `idempotency_in_progress` | The same keyed request is still processing. |
| 413 | `evidence_too_large` | Retrieved evidence exceeds the configured size limit. |
| 415 | `unsupported_evidence_media` | Retrieved evidence media is unsupported. |
| 422 | `unsupported_claim_scenario` | Domain is recognized but ClaimReady does not support its scenario. |
| 422 | `evidence_source_rejected` | Evidence source was rejected by remote-resource safety checks. |
| 429 | `rate_limit_exceeded` | Technical request rate was exceeded; follow `Retry-After` when supplied. |
| 429 | `quota_exceeded` | Current operation quota is exhausted. |
| 500 | `internal_error` | An unexpected error occurred. |
| 502 | `invalid_provider_output` | Processing output could not be represented by the public contract. |
| 502 | `provider_execution_failed` | Processing failed while handling the request. |
| 503 | `api_key_authentication_unavailable` | API key could not be safely validated. |
| 503 | `entitlement_check_unavailable` | Entitlement cannot currently be evaluated. |
| 503 | `idempotency_unavailable` | Idempotency service is unavailable. |
| 503 | `idempotency_replay_unavailable` | Original result cannot currently be restored. |
| 503 | `idempotency_completion_failed` | Idempotent completion could not be finalized. |
| 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 operation reservation could not be released. |
| 503 | `evidence_source_unavailable` | Evidence source could not be reached. |
| 503 | `provider_unavailable` | Processing service is temporarily unavailable. |
| 503 | `claim_triage_persistence_failed` | Triage result could not be stored. |
| 503 | `usage_recording_failed` | Triage Usage could not be recorded. |
| 503 | `rate_limit_unavailable` | Rate-limit evaluation is temporarily unavailable. |

## GET errors

| HTTP | Code | Meaning |
| -: | - | - |
| 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. |
| 500 | `request_context_unavailable` | Authenticated request context could not be read. |
| 404 | `claim_triage_not_found` | ID is missing, invalid, or not owned by this customer. |
| 503 | `claim_triage_retrieval_unavailable` | Stored result could not be retrieved. |
| 503 | `rate_limit_unavailable` | Rate-limit evaluation is temporarily unavailable. |
| 429 | `rate_limit_exceeded` | Technical request rate was exceeded. |

## Retry guidance

Correct request and authentication errors before retrying. For rate limits,
follow `Retry-After` when supplied. For quota exhaustion, wait until quota is
available or access changes. Retry temporary failures with bounded backoff.
Use the same `Idempotency-Key` for a retry of the same logical request. See
[Usage and quotas](https://docs.thewo.io/claim-ready/guides/usage-and-quotas.md#idempotency).


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