Troubleshoot Extraction

Use this section to troubleshoot issues encountered when calling the extraction APIs:

: /v1/ade/extract
: /v1/ade/extract/build-schema
ADE Extract Jobs: /v1/ade/extract/jobs
ADE Get Extract Jobs: /v1/ade/extract/jobs/
ADE List Extract Jobs: /v1/ade/extract/jobs

Common Status Codes

These status codes apply to all extraction endpoints.

Status Code	Name	Description	What to Do
401	Unauthorized	Missing or invalid API key.	Check that your `apikey` header is present and contains a valid 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. Add more credits to your account.
429	Too Many Requests	Rate limit exceeded.	Wait before retrying. Reduce request frequency and implement exponential backoff.

ADE Extract

This section covers errors for the API.

Status Codes

Status Code	Name	Description	What to Do
200	Success	Extraction completed successfully and extracted data conforms to the schema.	Continue with normal operations.
206	Partial Content	Extraction 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.
400	Bad Request	Invalid request due to malformed input, unsupported version, or client-side extraction errors.	Review error message for specific issue. See Status 400: Bad Request.
422	Unprocessable Entity	Input validation failed.	Review your request parameters. See Status 422: Unprocessable Entity.
500	Internal Server Error	Server error during processing.	Retry. If the issue persists, contact support@landing.ai. See Status 500: Internal Server Error.
504	Gateway Timeout	Request 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.

Extracted data does not completely conform to the requested schema

This occurs when the extracted data violates the JSON schema validation rules. The message includes details from the validation process. 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 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.

Null value returned

The API returns null when it cannot locate a field’s value in the document. This can occur because the data is not in the document, or because the API could not locate it. For more information, go to How the API Handles Missing Fields. Error message:

The value at 'field_name' was not found in the document, so null was returned. Since the schema requires a non-null value, verify that the document indeed doesn't contain this data, and if so, update the schema to allow null by adding 'null' to the field's type (e.g., type: ['string', 'null']) or by setting nullable: true.

What to do:

Check whether the document actually contains the expected data. If it does not, the null result is correct.
If the document does contain the data but the API could not find it, revise your schema to help the API locate the field:
- Add or refine the description to be more specific about what to extract.
- Add entries to x-alternativeNames that match how the field label appears in the document.
For more information, go to Field Descriptions and Alternative Names.

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:

Retry the request.
If the error persists, contact support@landing.ai.

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 Code	Description
`nonconformant_schema`	The schema contains issues that affected extraction.
`nonconformant_output`	The 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 Code	Name	Description	What to Do
200	Success	Schema generated successfully.	Continue with normal operations.
400	Bad Request	Invalid request due to a download failure, unsupported version, or invalid schema.	Review the error message for the specific issue. See errors below.
422	Unprocessable Entity	Input validation failed.	Review your request parameters. See errors below.
500	Internal Server Error	Server error during schema generation.	Retry. If the issue persists, contact support@landing.ai.
504	Gateway Timeout	Request 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’, ‘schema’, or ‘prompt’

This error occurs when your request does not include any input. Error message:

Must provide at least one of 'markdowns', 'markdown_urls', 'schema', or 'prompt'.

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.
prompt: A description of the schema you want to generate.

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:

Retry the request.
If the error persists, contact support@landing.ai.

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.

ADE Extract Jobs

This section covers errors for the Extract Jobs APIs:

ADE Extract Jobs creates a job.
ADE Get Extract Jobs returns the status and results for a job.
ADE List Extract Jobs lists your jobs.

The Common Status Codes also apply to these endpoints. The Extract Jobs APIs return errors in a message field, except for the create endpoint, which returns errors in an error field.

Create an Extract Job: Status Codes

These status codes apply to the ADE Extract Jobs API (/v1/ade/extract/jobs).

Status Code	Name	Description	What to Do
202	Accepted	The job was queued successfully. The response contains the `job_id`.	Poll the ADE Get Extract Jobs API with the `job_id` to track status and retrieve results.
400	Bad Request	Invalid request, such as an invalid JSON schema, an unreachable Markdown URL, or a zero data retention (ZDR) configuration error.	Review the error message. See Create an Extract Job: Status 400.
422	Unprocessable Entity	Input validation failed, such as a missing Markdown input or an unsupported file format.	Review your request parameters. See Create an Extract Job: Status 422.
429	Too Many Requests	Rate limit exceeded.	Wait before retrying. Each job counts as one submission toward your hourly limit, regardless of document size. See Rate Limits.
500	Internal Server Error	Server error while creating the job.	Retry. If the issue persists, contact support@landing.ai.

Create an Extract Job: Status 400: Bad Request

For an invalid JSON schema or an unreachable Markdown URL, the cause and fix match the API. See Error: Invalid JSON schema and Error: Failed to download document from URL. The following errors are specific to ZDR-enabled requests.

Error: output_save_url must be present if zeroDataRetention is enabled

This error occurs when ZDR is enabled but the request does not include the output_save_url parameter. Error message:

output_save_url must be present if zeroDataRetention is enabled

What to do: Include the output_save_url parameter so the extracted content is saved to your URL instead of being returned in the response. For more information, go to ZDR Requirements.

Error: Only markdown_url is accepted if zeroDataRetention is enabled

This error occurs when ZDR is enabled but the request uploads a local Markdown file with the markdown parameter. Error message:

Only markdown_url is accepted if zeroDataRetention is enabled

What to do: Pass your Markdown using the markdown_url parameter instead of uploading a local file. For more information, go to ZDR Requirements.

Create an Extract Job: Status 422: Unprocessable Entity

For a missing Markdown input or an unsupported file format, the messages and fixes match the API. See Error: No markdown file or URL provided and Error: Unsupported format.

Get an Extract Job: Status Codes

These status codes apply to the ADE Get Extract Jobs API (/v1/ade/extract/jobs/{job_id}).

Status Code	Name	Description	What to Do
200	Success	The job was retrieved. When `status` is `completed`, the response includes the extracted data.	Read the `status` field. If `failed`, see Failed Jobs.
206	Partial Content	The job completed, but the extracted data does not fully conform to the schema.	Review the `schema_violation_error` and `warnings` fields. See Status 206: Partial Content.
404	Not Found	No job with the given ID exists for your API key.	See Get an Extract Job: Status 404.
500	Internal Server Error	Server error while retrieving the job.	Retry. If the issue persists, contact support@landing.ai.

Failed Jobs

A 200 response with status set to failed means the job did not complete. The failure_reason field describes what went wrong. Because extraction runs in the background, errors that occur during processing (including timeouts) are reported here rather than as an HTTP error code on this endpoint. What to do:

Review the failure_reason field for the cause.
If the failure reason indicates a timeout, reduce the size of your Markdown document or simplify your extraction schema, then submit a new job.
Otherwise, verify your Markdown input and schema, then submit a new job.

Get an Extract Job: Status 404: Not Found

This error occurs when no job matches the job_id, or the job belongs to a different API key. Error message:

Job {job_id} not found

What to do:

Verify the job_id matches the value returned when you created the job.
Confirm you are using the same API key that created the job.

List Extract Jobs: Status Codes

These status codes apply to the ADE List Extract Jobs API (/v1/ade/extract/jobs).

Status Code	Name	Description	What to Do
200	Success	The list of jobs was retrieved.	Continue with normal operations.
422	Unprocessable Entity	Invalid query parameters, such as an out-of-range `page` or `pageSize`.	Review the `page`, `pageSize`, and `status` query parameters.
500	Internal Server Error	Server error while listing jobs.	Retry. If the issue 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.
ADE Extract Jobs: Credits are consumed only when a job reaches the completed status (including completions returned with a 206 status code). Failed and cancelled jobs do not consume credits.

Asynchronous Extraction (Extract Jobs)Classify

⌘I

​Common Status Codes

​ADE Extract

​Status Codes

​Status 206: Partial Content

​Extracted data does not completely conform to the requested schema

​Null value returned

​Status 400: Bad Request

​Error: Invalid JSON schema

​Error: Failed to download document from URL

​Error: Field extraction invalid

​Error: Invalid extract version

​Status 422: Unprocessable Entity

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

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

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

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

​Error: The following schema fields were not supported

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

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

​Error: No markdown file or URL provided

​Error: Invalid URL format

​Error: Multiple Markdown files detected

​Error: Unsupported format

​Status 500: Internal Server Error

​Status 504: Gateway Timeout

​Model Fallback Behavior

​Warnings

​ADE Build Extract Schema

​Status Codes

​Status 400: Bad Request

​Error: Invalid extract version

​Error: Failed to download document from URL

​Error: Schema generation invalid

​Status 422: Unprocessable Entity

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

​Error: Invalid URL format

​Error: Invalid existing schema JSON

​Error: Unsupported format

​Error: Schema generation validation error

​Status 500: Internal Server Error

​Status 504: Gateway Timeout

​ADE Extract Jobs

​Create an Extract Job: Status Codes

​Create an Extract Job: Status 400: Bad Request

Error: output_save_url must be present if zeroDataRetention is enabled

Error: Only markdown_url is accepted if zeroDataRetention is enabled

​Create an Extract Job: Status 422: Unprocessable Entity

​Get an Extract Job: Status Codes

​Failed Jobs

​Get an Extract Job: Status 404: Not Found

​List Extract Jobs: Status Codes

​When Are Credits Consumed?

Common Status Codes

ADE Extract

Status Codes

Status 206: Partial Content

Extracted data does not completely conform to the requested schema

Null value returned

Status 400: Bad Request

Error: Invalid JSON schema

Error: Failed to download document from URL

Error: Field extraction invalid

Error: Invalid extract version

Status 422: Unprocessable Entity

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

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

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

Error: The provided schema contains recursive local $ref cycles

Error: The following schema fields were not supported

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

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

Error: No markdown file or URL provided

Error: Invalid URL format

Error: Multiple Markdown files detected

Error: Unsupported format

Status 500: Internal Server Error

Status 504: Gateway Timeout

Model Fallback Behavior

Warnings

ADE Build Extract Schema

Status Codes

Status 400: Bad Request

Error: Invalid extract version

Error: Failed to download document from URL

Error: Schema generation invalid

Status 422: Unprocessable Entity

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

Error: Invalid URL format

Error: Invalid existing schema JSON

Error: Unsupported format

Error: Schema generation validation error

Status 500: Internal Server Error

Status 504: Gateway Timeout

ADE Extract Jobs

Create an Extract Job: Status Codes

Create an Extract Job: Status 400: Bad Request

Create an Extract Job: Status 422: Unprocessable Entity

Get an Extract Job: Status Codes

Failed Jobs

Get an Extract Job: Status 404: Not Found

List Extract Jobs: Status Codes

When Are Credits Consumed?