Skip to main content
Use this section to troubleshoot issues encountered when calling the new Parse API.

​
Common Status Codes

These status codes are handled at the account and gateway level and can apply to any request.
Status CodeNameDescriptionWhat to Do
401UnauthorizedMissing or invalid API key.Check that your Authorization header is present and contains a valid API key.
402Payment RequiredYour account does not have enough credits to complete processing.If you have multiple accounts, make sure you’re using the correct API key. Add more credits to your account.
403ForbiddenAPI access is not available on the free plan. Free-tier usage is limited to the in-app playground.Purchase credits to enable API access, or upgrade to a Team or Enterprise plan. See API Access on the Explore Plan.
429Too Many RequestsRate limit exceeded.Wait before retrying. Reduce request frequency and implement exponential backoff. See Rate Limits.

​
Parse Status Codes

Status CodeNameDescriptionWhat to Do
200SuccessDocument parsed successfully and returned immediately.Continue with normal operations.
206Partial ContentDocument parsed, but at least one page (and not all pages) failed during processing.Review the failed_pages field in the metadata. See Status 206.
400Bad RequestInvalid model version or invalid document_url.Review the error message for the specific issue. See Status 400.
413Payload Too LargeThe document exceeds the 50 MiB size limit.Reduce the document size. See Status 413.
422Unprocessable EntityInput validation failed.Review your request parameters. See Status 422.
500Internal Server ErrorAll pages failed to process.Retry. If the issue persists, contact support@landing.ai. See Status 500.

​
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.
For more on the response shape, see How Parse Works.

​
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 version by default.
  • Supply a valid version: the dpt-3-pro-latest alias, or a dated snapshot such as dpt-3-pro-20260515. See 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 413: Payload Too Large

This status code indicates 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. See Rate Limits for current size limits.

​
Status 422: Unprocessable Entity

This status code indicates input validation failures. Review the error message and adjust your request parameters.

​
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.
  • 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. 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.

​
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 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.

​
When Are Credits Consumed?

Credits are consumed only when the new Parse API returns a 200 or 206 status code. All other responses, including errors, do not consume credits.