# Troubleshooting

Most failures are actionable before you retry. Reuse the same `Idempotency-Key` only when replaying the exact same logical request after a timeout or transport error.

Source: https://docs.docushell.com/troubleshooting
Category: Support

## Related

- [Error codes](/error-codes.md): The full status-code table and the shared error envelope.
- [Rate limits](/rate-limits.md): Throttle behavior and backoff guidance for `429`.

## Parse And Resume Failures

| Code | Fix |
| --- | --- |
| `invalid_pdf` | Confirm the upload is a real PDF. The gateway checks magic bytes, not the extension. |
| `corrupt_pdf` | Re-export or repair the file, then resubmit. |
| `password_protected` | Decrypt the PDF before uploading. Password submission is not part of this lane. |
| `ocr_required` | Run OCR upstream, then resubmit the text-native PDF. |
| `invalid_page_range` | Use a selector like `1-3,5` that resolves inside the document bounds. |
| `page_limit_exceeded` | Narrow `page_range` or move to a plan with a higher parse cap. |

## The Job Succeeded But The Output Is Wrong

| Symptom | Try |
| --- | --- |
| Text in the wrong order | `reading_order=off` for less reconstruction, `reading_order=xycut` for more. |
| Tables missing cell groupings | `table_method=cluster`. |
| Headings and sections not detected | `use_struct_tree=true` if the PDF is tagged. |
| Line breaks collapsed | `keep_line_breaks=true`. |
| Page headers and footers missing | `include_header_footer=true`. |
| Figures missing from Markdown | `formats=markdown_with_images`. |

## Batch Download States

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | — | The requested format was never requested for this batch. |
| 425 | `batch_not_ready` | The batch or file has not reached a terminal state yet. |
| 409 | `batch_file_failed` | That file failed after enqueue. Other files may still download. |
| 410 | `output_expired` | The one-hour artifact TTL has passed. |

## Capacity And Retries

- `server_busy` and `backend_unavailable` are temporary. Back off, then retry with the same `Idempotency-Key` for the exact same request.
- `503` on the batch lane carries `Retry-After`. Honor it.
- Fix `400` failures before retrying — the same invalid input is rejected again.
- Log `request_id` from the error body or the `x-request-id` header in every support report.