> ## Documentation Index > Fetch the complete documentation index at: https://docs.landing.ai/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshoot Parsing > Resolve errors when parsing with the Parse v2 API using status codes, causes, and recommended fixes. export const dpt3 = 'DPT-3'; export const parseDpt3 = 'Parse'; export const ade = 'Agentic Document Extraction'; Use this section to troubleshoot issues encountered when calling the [Parse v2 API](https://docs.landing.ai/api-reference/parse/ade-parse). ## Common Status Codes These status codes are handled at the account and gateway level and can apply to any request. | Status Code | Name | Description | What to Do | | ----------- | ----------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | 401 | Unauthorized | Missing or invalid API key. | Check that your `Authorization` header is present and contains a valid [API key](./agentic-api-key). | | 402 | Payment Required | Your account does not have enough credits to complete processing. | If you have multiple accounts, make sure you're using the correct [API key](./agentic-api-key). Add more credits to your account. | | 429 | Too Many Requests | Rate limit exceeded. | Wait before retrying. Reduce request frequency and implement exponential backoff. See [Rate Limits](./rate-limits). | ## Parse Status Codes | Status Code | Name | Description | What to Do | | ----------- | --------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | 200 | Success | Document parsed successfully and returned immediately. | Continue with normal operations. | | 206 | Partial Content | Document parsed, but at least one page (and not all pages) failed during processing. | Review the `failed_pages` field in the metadata. See [Status 206](#status-206-partial-content). | | 400 | Bad Request | Invalid model version or invalid `document_url`. | Review the error message for the specific issue. See [Status 400](#status-400-bad-request). | | 422 | Unprocessable Entity | Input validation failed, including documents over the size limits. | Review your request parameters. See [Status 422](#status-422-unprocessable-entity). | | 500 | Internal Server Error | All pages failed to process. | Retry. If the issue persists, contact [support@landing.ai](mailto:support@landing.ai). See [Status 500](#status-500-internal-server-error). | ## Status 206: Partial Content This response occurs when the document was parsed successfully but at least one page (and not all pages) failed during processing. The response includes: * A 206 status code. * Parsed content for the successful pages. Each successful page has a `status` of `"ok"` in `structure.children`. * A `failed_pages` array in `metadata` listing which pages failed (0-indexed). * A `status` of `"failed"`, a `reason`, and a zero-length `span` on each failed page in `structure.children`. Because the API returns at least partial results, the call consumes credits. **What to do:** * Review `metadata.failed_pages` to identify which pages failed. * Review the `reason` on each failed page in `structure.children` for details. * Check whether the failed pages are corrupted or have unusual formatting. * If the issue persists with specific pages, contact [support@landing.ai](mailto:support@landing.ai). For more on the response shape, see [Parse API Response](./parse-response#metadata). ## Status 400: Bad Request This status code indicates an invalid model version or an invalid `document_url`. Review the specific error message to identify the issue. ### Error: Unknown Model Version This error occurs when the `model` form field specifies a version that is not registered. **Error message:** ``` Unknown parse version '{version}'. Available: {available} (or one of {aliases}). ``` **What to do:** * Omit the `model` field to use the latest {dpt3} version by default. * Supply a valid version: the `dpt-3-pro-latest` alias, or a dated snapshot such as `dpt-3-pro-20260710`. See [Model Version](./parse-input#model-version). ### Error: Invalid document\_url Scheme This error occurs when the `document_url` uses a scheme other than `http` or `https` (for example, `ftp://` or `file://`). **Error message:** ``` document_url scheme must be http or https, got '{scheme}' ``` **What to do:** Supply a `document_url` that begins with `http://` or `https://`. ### Error: document\_url Missing Hostname This error occurs when the `document_url` does not contain a hostname. **Error message:** ``` document_url missing hostname ``` **What to do:** Verify the URL is complete and properly formatted, including a hostname (for example, `https://example.com/file.pdf`). ### Error: document\_url Did Not Resolve This error occurs when the `document_url` hostname cannot be resolved through DNS. **Error message:** ``` document_url hostname did not resolve: {hostname} ``` **What to do:** * Verify the hostname is spelled correctly. * Confirm the host is publicly reachable. ### Error: document\_url Resolves to a Non-Public IP This error occurs when the `document_url` hostname resolves to a private, loopback, link-local, reserved, or multicast IP address. Only publicly reachable URLs are allowed. **Error message:** ``` document_url resolves to a non-public IP: {ip} ``` **What to do:** Host the document at a publicly accessible URL, or upload the file directly using the `document` parameter. ### Error: document\_url Returned a Redirect This error occurs when the `document_url` responds with a redirect (301, 302, 303, 307, or 308). The server does not follow redirects; the URL must serve the file bytes directly. **Error message:** ``` document_url returned a redirect; supply the final URL directly. ``` **What to do:** Resolve the redirect yourself and supply the final destination URL that serves the file directly. ## Status 422: Unprocessable Entity This status code indicates input validation failures. Review the error message and adjust your request parameters. ### Error: Document Exceeds the Size Cap This error occurs when the document exceeds the 50 MiB size limit. The limit applies whether you upload the file directly (`document`) or supply a URL (`document_url`). **Error message:** ``` document exceeds 50 MiB cap ``` or ``` document_url body exceeds 50 MiB cap ``` **What to do:** * Reduce the document size to 50 MiB or less. * Split larger documents into smaller files, or submit the document to [Parse Jobs](./parse-async), which accepts documents up to 1 GiB. See [Rate Limits](./rate-limits) for current size limits. ### Error: Must Provide a Document This error occurs when your request includes neither the `document` nor the `document_url` parameter. **Error message:** ``` One of `document` or `document_url` is required. ``` **What to do:** Add one of these parameters to your request: * Use the `document` parameter to upload a file. * Use the `document_url` parameter to provide a URL to a file. ### Error: Cannot Provide Both document and document\_url This error occurs when both a file and a URL are provided in the same request. **Error message:** ``` Provide exactly one of `document` or `document_url`, not both. ``` **What to do:** Choose one input method and remove the other from your request. ### Error: Empty File This error occurs when the uploaded file contains no data. **Error message:** ``` Empty file ({filename}). ``` **What to do:** Upload a valid file that contains content. ### Error: Unsupported or Unrecognized File Format This error occurs when the file is not a supported PDF or image. The format is detected from the file's content, not its extension or Content-Type header. **Error message:** ``` Unsupported format: {format} ({filename}). ``` or ``` Unrecognised file format ({filename}). ``` **What to do:** * Convert your document to a supported format before uploading. See [Supported File Types](./file-types). * Verify the file is not corrupted by opening it in the appropriate application. ### Error: Too Many Pages This error occurs when a PDF exceeds the 100-page per-request limit. See [Rate Limits](./rate-limits#parse-v2-api). **Error message:** ``` document has {N} pages; the per-request limit is 100 ``` **What to do:** * Split the PDF into files of 100 pages or fewer and parse them separately. * Or submit the document to [Parse Jobs](./parse-async), which accepts up to 6,000 pages per PDF. ### Error: Failed to Fetch document\_url This error occurs when the server cannot retrieve the file from the `document_url`. The URL returned an HTTP error status, or the request failed (for example, a connection or timeout error). **Error message:** ``` Failed to fetch document_url: HTTP {status} ``` or ``` document_url fetch failed: {error_type} ``` **What to do:** * Verify the URL is accessible and returns the file directly. * Check that the URL does not require authentication. * Confirm the host is reachable and responds within the timeout. ### Error: Invalid options Value This error occurs when the `options` form field is not valid JSON, or when its contents fail validation (for example, a negative page index). **Error message:** ``` options: invalid JSON: {details} ``` or ``` options: {details} ``` **What to do:** * Ensure `options` is a valid JSON object. * Use 0-indexed, non-negative values in `pages`. * See [Request Options](./parse-input#request-options) for the full schema. ## Status 500: Internal Server Error This status code indicates that every page in the document failed to process. The response body is still a full parse response: each page in `structure.children` carries a `status` of `"failed"` and a `reason`, and `metadata.failed_pages` lists every page. **What to do:** * Retry the request. * Review the `reason` on the failed pages for details. * Check whether the document has unusual formatting or corrupted content. * If the error persists, contact [support@landing.ai](mailto:support@landing.ai). ## When Are Credits Consumed? Credits are consumed only when the Parse v2 API returns a 200 or 206 status code. All other responses, including errors, do not consume credits. ## Parse Jobs This section covers error and status behavior specific to [Parse Jobs v2](./parse-async), the asynchronous Parse API. Errors surface in two places: as HTTP status codes when you create or poll a job, and as a terminal `failed` job status when parsing itself fails. ### Job Creation Errors Creating a job with `POST /v2/parse/jobs` returns these status codes: | Status | Meaning | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `202 Accepted` | The job was created. The response contains the `job_id`. | | `400 Bad Request` | The `model` value is not a recognized version. | | `422 Unprocessable Entity` | The request is invalid: an encrypted PDF, malformed `options`, an invalid `service_tier` value, a PDF with more than 6,000 pages, or a document over the size limits (1 GiB for PDFs, 50 MiB for images). | | `429 Too Many Requests` | You exceeded your rate limit. | | `500 Internal Server Error` | The job could not be queued. Retry the request. | ### Polling Errors Polling a job with `GET /v2/parse/jobs/{job_id}` returns these status codes: | Status | Meaning | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `200 OK` | The job status was retrieved. Check the `status` field. | | `206 Partial Content` | The job completed, but some pages failed to parse. The result still contains every page; failed pages carry a `status` of `"failed"`. | | `404 Not Found` | No job with that `job_id` exists for your account. | ### Failed Jobs When parsing fails after a job starts, the poll request still returns `200`. The failure is reported in the job itself: `status` is `failed` and `failure_reason` describes the cause. Review the reason and resubmit the job to retry.