> ## 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 Extraction

export const adePythonLibrary = 'ade-python';

export const dpt2 = 'DPT-2';

export const dpt1 = 'DPT-1';

export const dpt = 'Document Pre-Trained Transformer';

export const companyName = 'LandingAI';

export const buildExtract = 'ADE Build Extract Schema';

export const extract = 'ADE Extract';

export const parse = 'ADE Parse';

export const ade = 'Agentic Document Extraction';

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

* **[{extract}](https://docs.landing.ai/api-reference/tools/ade-extract)**: /v1/ade/extract
* **[{buildExtract}](https://docs.landing.ai/api-reference/tools/ade-build-schema)**: /v1/ade/extract/build-schema

## 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](./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.                                                 |

## ADE Extract

This section covers errors for the {extract} 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](#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](#status-400-bad-request).                                                                   |
| 422         | Unprocessable Entity  | Input validation failed.                                                                       | Review your request parameters. See [Status 422: Unprocessable Entity](#status-422-unprocessable-entity).                                                          |
| 500         | Internal Server Error | Server error during processing.                                                                | Retry. If the issue persists, contact [support@landing.ai](mailto:support@landing.ai). See [Status 500: Internal Server Error](#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-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](#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)](./ade-extract-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)](./ade-extract-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](./ade-extract-schema-json#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](./ade-extract-schema-json#field-descriptions) and [Alternative Names](./ade-extract-schema-json#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)](./ade-extract-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)](./ade-extract-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](./ade-extract-models#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:**

```json {2} theme={null}
{
  "type": "object",
  "properties": {
    "invoice_number": {
      "type": "string",
      "description": "Invoice number"
    }
  }
}
```

**Incorrect:**

```json {2} theme={null}
{
  "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:**

```json {1,8} theme={null}
{
  "type": "object",
  "properties": {
    "invoice_number": {"type": "string"},
    "vendor_name": {"type": "string"},
    "total": {"type": "number"}
  }
}
```

**Incorrect:**

```json theme={null}
["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)](./ade-extract-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](./ade-extract-schema-json#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](./ade-extract#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](./ade-extract-schema-json#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](https://docs.landing.ai/api-reference/tools/ade-parse) 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](mailto: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)](./ade-extract-schema-json). Update your JSON schema if needed.
* If the error persists, contact [support@landing.ai](mailto: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](./ade-extract-response).

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](./ade-extract-models).

### 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-extract-response#processing-metadata-metadata).

## ADE Build Extract Schema

This section covers errors for the {buildExtract} 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](mailto: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](./ade-extract-models#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](https://docs.landing.ai/api-reference/tools/ade-parse) 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](mailto: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](mailto:support@landing.ai).

## When Are Credits Consumed?

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