Skip to main content
Use this section to troubleshoot issues encountered when calling the extraction APIs:
  • : /v1/ade/extract
  • : /v1/ade/extract/build-schema

​
Common Status Codes

These status codes apply to all extraction endpoints.
Status CodeNameDescriptionWhat to Do
401UnauthorizedMissing or invalid API key.Check that your apikey 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.
429Too Many RequestsRate limit exceeded.Wait before retrying. Reduce request frequency and implement exponential backoff.

​
ADE Extract

This section covers errors for the API.

​
Status Codes

Status CodeNameDescriptionWhat to Do
200SuccessExtraction completed successfully and extracted data conforms to the schema.Continue with normal operations.
206Partial ContentExtraction completed but extracted data does not fully conform to the schema.Review the schema_violation_error field in the response and adjust your schema or document. See Status 206: Partial Content.
400Bad RequestInvalid request due to malformed input, unsupported version, or client-side extraction errors.Review error message for specific issue. See Status 400: Bad Request.
422Unprocessable EntityInput validation failed.Review your request parameters. See Status 422: Unprocessable Entity.
500Internal Server ErrorServer error during processing.Retry. If the issue persists, contact support@landing.ai. See Status 500: Internal Server Error.
504Gateway TimeoutRequest processing exceeded the timeout limit (475 seconds).Reduce document size or simplify extraction schema. See Status 504: Gateway Timeout.

​
Status 206: Partial Content

This response occurs when extraction completes successfully but the extracted data does not fully conform to the provided JSON schema. The API returns a 206 status code with the extracted data and a schema_violation_error field that contains details about the validation failure. For extract-20260314 and above, the metadata.warnings field also contains structured warning objects. See Warnings. The errors in this section may appear in the schema_violation_error field when you receive a 206 status code. Because the API returns at least partial results, the API call consumes credits. What to do:
  • Review the specific validation error in the schema_violation_error field.
  • Verify the JSON schema follows the guidelines described in Extraction Schema (JSON). Update your JSON schema if needed.
  • Check if the document contains the expected data in the expected format.

​
Error: Extracted data does not completely conform to the requested schema

This error occurs when the extracted data violates the JSON schema validation rules. The error message includes details from the validation process. Error message: 
Extracted data does not completely conform to the requested schema. See below error for details.
{validation_error_details}
Please read our documentation for more information: https://docs.landing.ai/ade/ade-extract-troubleshoot
What to do:
  • Review the validation error details to identify the specific schema violation.
  • Verify the JSON schema follows the guidelines described in Extraction Schema (JSON). Update your JSON schema if needed.
  • Check if the document contains the expected data in the expected format.

​
Error: Schema violation: None is not of type ‘TYPE’

This error occurs when a field in the extracted output contains a null value but the field is not declared as nullable in the schema. Error message: 
Schema violation at 'field_name': None is not of type 'string'
What to do: Mark the field as nullable using the nullable keyword. For more information, go to Ignored Keywords.

​
Status 400: Bad Request

This status code indicates invalid request parameters or client-side errors. Review the specific error message to identify the issue.

​
Error: Invalid JSON schema

This error occurs when the extraction_schema parameter contains invalid JSON. Error message: 
Invalid JSON schema: Expecting value: line 1 column 1 (char 0)
What to do:
  • Verify your extraction schema is valid JSON.
  • Check for syntax errors (missing commas, quotes, brackets).
  • Verify the JSON schema follows the guidelines described in Extraction Schema (JSON). Update your JSON schema if needed.

​
Error: Failed to download document from URL

This error occurs when the API cannot download the Markdown file from the provided markdown_url. Error message: 
Failed to download document from URL: {error_details}
What to do:
  • Verify the URL is accessible and returns valid content.
  • Check network connectivity and URL permissions.
  • Ensure the URL points to a Markdown file (.md extension).

​
Error: Field extraction invalid

This error occurs when the extraction process fails due to issues with the extraction schema or the extracted data. Error message: 
Field extraction invalid: {error_details}
What to do:
  • Review the error details in the response.
  • Verify the JSON schema follows the guidelines described in Extraction Schema (JSON). Update your JSON schema if needed.
  • Ensure all required fields are properly defined in the schema.
  • Check if the document contains data that matches the schema structure.

​
Error: Invalid extract version

This error occurs when an unsupported model version is specified. Error message: 
Invalid extract version '{version}' provided. Valid versions are: {list_of_versions} or use 'extract-latest' to use the latest version.
What to do:
  • Use one of the supported versions listed in the error message.
  • Use extract-latest to automatically use the latest version.
  • If you don’t specify a version, the API uses the latest version by default.
  • For more information, go to Extraction Model Versions.

​
Status 422: Unprocessable Entity

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

​
Error: The provided schema must have “type”: “object” for the root

This error occurs when the extraction_schema is a valid JSON object, but its type keyword is not set to "object". The extraction engine requires the root schema to explicitly declare "type": "object". Error message: 
Field extraction validation error: The provided schema must have "type": "object" for the root.
What to do: Set "type": "object" at the root of your schema. Correct: 
{
  "type": "object",
  "properties": {
    "invoice_number": {
      "type": "string",
      "description": "Invoice number"
    }
  }
}
Incorrect: 
{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "invoice_number": {
        "type": "string",
        "description": "Invoice number"
      }
    }
  }
}

​
Error: The provided JSON must parse to an object at the root

This error occurs when the extraction_schema parameter is valid JSON, but the root value is not a JSON object. For example, the root is a JSON array ([...]), a string, or a number rather than {...}. Error message: 
Field extraction validation error: The provided JSON must parse to an object at the root.
What to do: Wrap your schema in a JSON object ({...}). Correct: 
{
  "type": "object",
  "properties": {
    "invoice_number": {"type": "string"},
    "vendor_name": {"type": "string"},
    "total": {"type": "number"}
  }
}
Incorrect: 
["invoice_number", "vendor_name", "total"]

​
Error: The provided JSON object was not a valid JSON schema

This error occurs when the extraction_schema parameter contains a JSON object that does not conform to the JSON Schema specification. Error message: 
Field extraction validation error: The provided JSON object was not a valid JSON schema. Error: {error_details}
What to do:
  • Review the error details to identify the specific schema issue.
  • Verify your schema follows the guidelines described in Extraction Schema (JSON).

​
Error: The provided schema contains recursive local $ref cycles

This error occurs when the extraction schema contains circular $ref references (for example, a schema that references itself). Error message: 
Field extraction validation error: The provided schema contains recursive local `$ref` cycles, which are not supported.
What to do: Remove circular $ref references from your schema. Restructure nested types to avoid self-referencing definitions.

​
Error: The following schema fields were not supported

This error occurs when the extraction schema contains keywords that cause errors and the strict parameter is set to true. When strict is false, the API removes the unsupported keywords and continues processing. The API returns 200 if extraction succeeds with valid output, or 206 if the extracted output does not conform to the original schema. For more information, go to Set the strict Parameter. Error message: 
Field extraction validation error: The following schema fields were not supported: {keywords}
What to do:
  • Remove the unsupported keywords listed in the error message from your schema.
  • For a list of keywords that cause errors, go to Keywords That Cause Errors.

​
Error: Cannot provide both ‘markdown’ and ‘markdown_url’

This error occurs when both a Markdown file and a URL to a Markdown file are provided in the same request. Error message: 
Cannot provide both 'markdown' and 'markdown_url'. Please provide only one.
What to do: Choose one input method:
  • Provide a Markdown file using the markdown parameter, OR
  • Provide a URL to a Markdown file using the markdown_url parameter.

​
Error: Must provide either ‘markdown’ or ‘markdown_url’

This error occurs when your request does not include either the markdown or markdown_url parameter. Error message: 
Must provide either 'markdown' or 'markdown_url'.
What to do: Add one of these parameters to your request:
  • Use the markdown parameter to upload a Markdown file, OR
  • Use the markdown_url parameter to provide a URL to a Markdown file.

​
Error: No markdown file or URL provided

This error occurs when you include a markdown or markdown_url parameter in your request, but the value is empty or blank. Error message: 
No markdown file or URL provided.
What to do:
  • If using markdown: Ensure you are uploading a valid Markdown file (not an empty file or blank value).
  • If using markdown_url: Ensure the parameter contains a valid URL (not an empty string or blank value).
  • Verify that your request properly includes the file or URL value.

​
Error: Invalid URL format

This error occurs when the markdown_url parameter contains a value that is not a valid URL. Error message: 
Invalid URL format: {url}
What to do:
  • Verify the URL is properly formatted with a valid protocol (http:// or https://).
  • Check for typos or missing characters in the URL.
  • Ensure the URL is properly encoded if it contains special characters.

​
Error: Multiple Markdown files detected

This error occurs when multiple Markdown files are included in the request. Error message: 
Multiple markdown files detected (X). Please provide only one document file.
What to do: Send only one Markdown file per request.

​
Error: Unsupported format

This error occurs when you provide a file other than Markdown (.md) to the extract endpoint, such as PDF, DOCX, XLSX, or image files. Error message: 
Unsupported format: {mime_type} ({filename}). Supported formats: MD
What to do:
  • The extract endpoint only accepts Markdown files with a .md extension.
  • If you have a PDF, DOCX, or other document format, use the Parse API endpoint to convert your document to Markdown first.
  • Ensure your file has a .md extension and contains valid UTF-8 encoded Markdown content.

​
Status 500: Internal Server Error

This error indicates an unexpected server error occurred during processing. What to do:

​
Status 504: Gateway Timeout

This error occurs when the extraction process exceeds the timeout limit (475 seconds). Error message: 
Request timed out after 475 seconds
What to do:
  • Reduce the size of your Markdown document.
  • Simplify your extraction schema and verify it follows the guidelines described in Extraction Schema (JSON). Update your JSON schema if needed.
  • If the error persists, contact support@landing.ai.

​
Model Fallback Behavior

The metadata.fallback_model_version field is included in the API response to support legacy behavior. When using extract-20251024, the API may automatically fall back to extract-20250930 if your JSON schema is too complex. If a fallback occurred, metadata.fallback_model_version contains the model version that was used instead. For more information about the response structure, go to JSON Response for Extraction. When using extract-20260314, the API does not fall back to an earlier model. What to do: To avoid unexpected fallback behavior, use the most recent extraction model. For more information, go to Extraction Model Versions.

​
Warnings

For extract-20260314, the metadata.warnings field contains an array of structured warning objects. Each warning has a code that identifies the warning type and a msg with a human-readable description. If you use an earlier extraction model version, this field is absent from the response. Any warning in the warnings array causes the API to return a 206 status code. The following warning codes can appear:
Warning CodeDescription
nonconformant_schemaThe schema contains issues that affected extraction.
nonconformant_outputThe extracted output does not fully conform to the schema. This warning also populates the schema_violation_error field for backward compatibility.
For more information about the response structure, go to JSON Response for Extraction.

​
ADE Build Extract Schema

This section covers errors for the API.

​
Status Codes

Status CodeNameDescriptionWhat to Do
200SuccessSchema generated successfully.Continue with normal operations.
400Bad RequestInvalid request due to a download failure, unsupported version, or invalid schema.Review the error message for the specific issue. See errors below.
422Unprocessable EntityInput validation failed.Review your request parameters. See errors below.
500Internal Server ErrorServer error during schema generation.Retry. If the issue persists, contact support@landing.ai.
504Gateway TimeoutRequest processing exceeded the timeout limit (475 seconds).Reduce document size. See errors below.

​
Status 400: Bad Request

This status code indicates invalid request parameters or client-side errors. Review the specific error message to identify the issue.

​
Error: Invalid extract version

This error occurs when an unsupported model version is specified. Error message: 
Invalid extract version '{version}' provided. Valid versions are: {list_of_versions} or use 'extract-latest' to use the latest version.
What to do:
  • Use one of the supported versions listed in the error message.
  • Use extract-latest to automatically use the latest version.
  • If you don’t specify a version, the API uses the latest version by default.
  • For more information, go to Extraction Model Versions.

​
Error: Failed to download document from URL

This error occurs when the API cannot download a Markdown file from one of the provided markdown_urls. Error message: 
Failed to download document from URL {url}: {error_details}
What to do:
  • Verify each URL is accessible and returns valid content.
  • Check network connectivity and URL permissions.
  • Ensure each URL points to a Markdown file (.md extension).

​
Error: Schema generation invalid

This error occurs when the schema generation request is rejected by the processing service. Error message: 
Schema generation invalid: {error_details}
What to do:
  • Review the error details in the response.
  • Check that any provided schema parameter is valid JSON.
  • Verify that your Markdown content is readable and well-formed.

​
Status 422: Unprocessable Entity

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

​
Error: Must provide at least one of ‘markdowns’, ‘markdown_urls’, or ‘schema’

This error occurs when your request does not include any input. Error message: 
Must provide at least one of 'markdowns', 'markdown_urls', or 'schema'.
What to do: Add at least one of the following to your request:
  • markdowns: One or more Markdown files or inline Markdown strings.
  • markdown_urls: One or more URLs to Markdown files.
  • schema: An existing JSON schema to refine.

​
Error: Invalid URL format

This error occurs when a URL in the markdown_urls parameter is not a valid URL. Error message: 
Invalid URL format: {url}
What to do:
  • Verify the URL is properly formatted with a valid protocol (http:// or https://).
  • Check for typos or missing characters in the URL.
  • Ensure the URL is properly encoded if it contains special characters.

​
Error: Invalid existing schema JSON

This error occurs when the schema parameter contains invalid JSON. Error message: 
Invalid existing schema JSON: {error_details}
What to do:
  • Verify your schema is valid JSON.
  • Check for syntax errors (missing commas, quotes, or brackets).

​
Error: Unsupported format

This error occurs when a file provided via markdowns or markdown_urls is not a Markdown (.md) file. Error message: 
Unsupported format: {mime_type} ({filename}). Supported formats: MD
What to do:
  • The build-schema endpoint only accepts Markdown files with a .md extension.
  • If you have a PDF, DOCX, or other document format, use the Parse API to convert it to Markdown first.
  • Ensure your file has a .md extension and contains valid UTF-8 encoded Markdown content.

​
Error: Schema generation validation error

This error occurs when the schema generation request fails validation in the processing service. Error message: 
Schema generation validation error: {error_details}
What to do:
  • Review the error details in the response.
  • Check that your inputs are valid: well-formed Markdown content, valid JSON for the schema parameter, and clear instructions in the prompt parameter.

​
Status 500: Internal Server Error

This error indicates an unexpected server error occurred during schema generation. What to do:

​
Status 504: Gateway Timeout

This error occurs when schema generation exceeds the timeout limit (475 seconds). Error message: 
Request timed out after {seconds} seconds
What to do:
  • Reduce the size and number of Markdown files in the request.
  • If the error persists, contact support@landing.ai.

​
When Are Credits Consumed?

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