Every error, one table.

These are API errors: status: "error", a rejected request. For a response that came back status: "success" with text that's still wrong (mojibake, empty, scrambled columns), see fixes for broken extracted text instead.

Every non-success response has the same shape:

{
  "status": "error",
  "error": {
    "code": "too_large",
    "message": "upload exceeds max size of 10485760 bytes; use ?url= for larger documents"
  }
}

Match on error.code. It's stable across releases. error.message is human-readable detail and can change. Don't parse it.

Locked files: a locked PDF returns encrypted, and a locked Word or Excel file returns extraction_failed. See Password-protected files for real output and how to unlock a file first.

rate_limited-vs-quota

Both are 429s, but they mean different things. rate_limited is your API key's per-minute request rate. It counts every accepted request, including ones that go on to fail. It resets every minute. It carries a Retry-After header (in seconds) plus X-RateLimit-Limit/X-RateLimit-Remaining/X-RateLimit-Reset headers, so you can back off precisely. quota_exceeded is your plan's monthly document quota. It counts only successful extractions. It's checked after the rate-limit gate, and it also carries X-Quota-Limit/X-Quota-Remaining/X-Quota-Reset. Wait for the reset or upgrade your plan.

quota_exceeded (429) is your plan's monthly document quota. It counts only successful extractions, so failed requests never burn it. It resets once per UTC month. The response carries a Retry-After header (seconds until that reset) and X-Quota-Limit/X-Quota-Remaining/X-Quota-Reset headers. It also carries the X-RateLimit-* triad, since the rate check runs first. Those headers are always present too. Match on error.code to tell the two 429s apart, not on the status alone. X-Quota-* headers also ride on every successful 200/202 response, so you can budget ahead of time instead of waiting to hit the limit.

authentication-failures

A missing Authorization header returns 401; an invalid or revoked key returns 403. Both come back with API Gateway's own {"message": "…"} body. This is deliberately not the typed {"error": {"code": …}} envelope above. That's a platform limit of the HTTP-API authorizer, not something this API controls. Integrators should match on HTTP status for auth failures, never on a code field. A revoked key can take up to 60 seconds to stop working (the authorizer caches its allow/deny decision for that long). Create a key in your dashboard.

the-actual-thresholds

too_large, timeout, fetch_failed, and rate_limited each name a rule, not a number. The current byte and time thresholds behind all four, and everything else the API enforces, are on the limits page →.

typed-exceptions

Both official SDKs map every code above to its own exception class (for example, TooLargeError, UnsupportedFormatError). Each class derives from a common TxtfetchError. See the quickstarts for the full class list.

machine-readable-spec

This table is generated at build time from the published OpenAPI 3.1 spec's ErrorCode enum and per-code HTTP status. The build fails if this page's editorial guidance ever falls out of sync with the contract.