> ## 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). ## Error Response Format Every error from the v2 APIs returns a JSON body with two fields: ```json theme={null} { "code": "unknown_model_version", "message": "Unknown model version 'dpt-2'. Available: dpt-3-pro-20260710, dpt-3-pro-latest." } ``` The `code` field is a stable snake\_case identifier you can branch on, such as `validation_error`, `unknown_model_version`, `invalid_url`, `invalid_api_key`, or `rate_limit_exceeded`. The `message` field is a human-readable description; treat its exact wording as variable. The error messages quoted on this page are `message` values. ## 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). | | 502 | Bad Gateway | A transient infrastructure error interrupted the request. | Retry with exponential backoff. A synchronous request that fails to deliver a result is not billed. | | 503 | Service Unavailable | The service is temporarily unavailable. | Retry with exponential backoff. If the error persists, contact [support@landing.ai](mailto:support@landing.ai). | ## 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). | | 422 | Unprocessable Entity | Input validation failed, including an unknown model version, an invalid `document_url`, or a document 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). | | 504 | Gateway Timeout | Request processing exceeded the timeout limit (475 seconds). | Reduce the number of pages per request or use Parse Jobs. See [Status 504](#status-504-gateway-timeout). | ## 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 (1-indexed). * A `status` of `"failed"`, a `reason`, and a zero-length `range` 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 422: Unprocessable Entity This status code indicates input validation failures. Review the error `message` and adjust your request parameters. ### Error: Unknown Model Version This error occurs when the `model` form field specifies a version that is not registered. The error `code` is `unknown_model_version`. **Error message:** ``` Unknown model version '{version}'. Available: {versions}. ``` **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. The error `code` is `invalid_url`. **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. ### Error: document\_url Fetch Failed This error occurs when the URL passes validation but the file cannot be fetched: the server returns an error status, times out, or refuses the connection. **Error message:** ``` Failed to fetch document_url: HTTP 404 ``` or ``` Failed to fetch document_url: request timed out ``` or ``` Failed to fetch document_url: connection failed ``` **What to do:** * Verify the URL serves the file and is publicly reachable. * If the URL is presigned, confirm it has not expired. ### 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: Page Numbers Must Be 1-Indexed This error occurs when the `options.pages` selector includes `0` or a negative number. Page numbers are 1-indexed: `1` is the document's first page. Page numbers beyond the document's length do not cause an error; they are silently ignored. **Error message:** ``` pages: page numbers are 1-indexed (must be >= 1), got: [0] ``` **What to do:** Update the `pages` values to 1-indexed page numbers. For example, to parse the first and third pages, send `{"pages": [1, 3]}`. ### 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, when its contents fail validation, or when it contains a key the API does not recognize. Unknown keys are rejected at every nesting level, including the retired legacy options `dpi`, `grounding`, and `blocks..caption`. **Error message:** ``` options: invalid JSON: {details} ``` or ``` options.dpi: Extra inputs are not permitted ``` **What to do:** * Ensure `options` is a valid JSON object. * Remove any option key named in the message. If the key is a legacy option, use its replacement: `blocks..markdown` instead of `blocks..caption`, and `atomic_grounding` instead of `grounding.parts`. The `dpi` option has no replacement; coordinates are normalized. * Use 1-indexed page numbers in `pages`. See [Page Numbers Must Be 1-Indexed](#error-page-numbers-must-be-1-indexed). * See [Request Options](./parse-input#request-options) for the full schema. ### Error: service\_tier Is Only Valid on Parse Jobs This error occurs when a request to the synchronous Parse endpoint (`POST /v2/parse`) includes the `service_tier` parameter. Service tiers only apply to asynchronous endpoints, like Parse Jobs. The parameter is rejected even when its value is empty. **Error message:** ``` service_tier (or its deprecated alias priority) is only valid on the async POST /v2/parse/jobs route; sync runs in the fast lane already ``` **What to do:** * Remove the `service_tier` parameter from Parse requests. Parse always runs on the `priority` tier. See [Sync vs Async Processing](./sync-async). * To choose a service tier, create a Parse Job instead. See [Choose a Service Tier](./parse-async#choose-a-service-tier). ## 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). ## Status 504: Gateway Timeout This error occurs when a synchronous parse request exceeds the timeout limit (475 seconds). The work is cancelled, so retrying starts the parse from the beginning. You are not billed for a request that times out. **Error message:** ``` parse did not complete within 475s; use POST /v2/parse/jobs for long-running work ``` **What to do:** * Reduce the number of pages per request with the `pages` option, or split the document into smaller files. See [Request Options](./parse-input#request-options). * Use [Parse Jobs](./parse-async) instead. Jobs are not subject to the synchronous timeout and accept larger documents. See [Sync vs Async Processing](./sync-async). * 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`. | | `422 Unprocessable Entity` | The request is invalid: an unrecognized `model` version, 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 the `error` field carries a `code` and a `message` describing the cause. Jobs have a maximum run time of 6 hours; a job that exceeds it fails. Review the error and resubmit the job to retry.