Errors
HTTP status codes Untangled returns and what each one means.
Every error response is JSON in the same shape:
{
"error": {
"code": "invalid_api_key",
"message": "The API key is missing, malformed, or has been revoked.",
"details": {
"requestId": "req_01HXXXX"
}
}
}If a response includes error.details.requestId, attach that value when filing a support ticket. We can locate any request by it.
Status codes
| Status | error.code | When |
|---|---|---|
| 400 | invalid_request | Body failed JSON parse or schema validation. |
| 400 | document_too_large | The submitted document exceeded the per-call size cap. Split or use /v1/extract/batch. |
| 401 | invalid_api_key | Missing, malformed, or revoked x-api-key. |
| 402 | plan_limit_exceeded | Free plan hit the HEU bucket; paid plans only see this if billing is past-due. |
| 404 | not_found | The path or resource (batch ID, schema slug) doesn't exist. |
| 409 | idempotency_conflict | Same Idempotency-Key reused on a different request body. |
| 422 | extract_failed | The document parsed but no schema-conformant data could be produced. |
| 429 | too_many_requests | Plan concurrency cap or per-IP rate limit. Retry after the Retry-After header. |
| 500 | internal_error | Untangled's fault. Retries with the same Idempotency-Key are safe. |
| 503 | service_unavailable | Upstream model temporarily down. Retry with backoff. |
Retry policy
429and5xxare retryable. Use exponential backoff starting at 1s, max 30s.4xxother than429are not retryable — the request body needs to change.- Idempotency keys make retries safe — pass
Idempotency-Key: <uuid>and a duplicate within 5 minutes returns the original response without re-charging HEU.
Clock-skew note
429 responses include a Retry-After header in seconds. Use that exact value. Do not derive a retry time from local clock arithmetic — the server clock is the source of truth.