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

> Resolve Extract errors using status codes, causes, and fixes.

export const dpt3 = 'DPT-3';

export const extractDpt3 = 'Extract';

export const parseDpt3 = 'Parse';

export const ade = 'Agentic Document Extraction';

Use this section to troubleshoot issues encountered when calling the Extract API (`/v2/extract`) and Extract Jobs (`/v2/extract/jobs`).

## 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).               |

## Status Codes

| Status Code | Name                  | Description                                                                                    | What to Do                                                                                                                                                         |
| ----------- | --------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 200         | Success               | Extraction completed successfully.                                                             | Continue with normal operations.                                                                                                                                   |
| 400         | Bad Request           | Invalid request due to malformed input, unsupported version, or client-side extraction errors. | Review the error message for the specific issue. See [Status 400: Bad Request](#status-400-bad-request).                                                           |
| 413         | Payload Too Large     | The request payload exceeds the maximum allowed size.                                          | Reduce the size of the Markdown you send.                                                                                                                          |
| 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.                                                 | Reduce document size or simplify the extraction schema. See [Status 504: Gateway Timeout](#status-504-gateway-timeout).                                            |

## 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: 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 [Model Version](./extract-input#model-version).

## Status 422: Unprocessable Entity

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

### Error: The provided schema is not valid JSON

This error occurs when the `schema` parameter cannot be parsed as JSON.

**Error message:**

```
The provided string is not valid JSON, let alone a schema.
```

**What to do:**

* Verify your extraction schema is valid JSON.
* Check for syntax errors such as missing commas, quotes, or brackets.
* See [Extraction Schema (JSON)](./ade-extract-schema-json) for the required structure.

### Error: The provided schema must have "type": "object" for the root

This error occurs when the `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 `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 `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.
* Check that every `type` value is a JSON Schema type (`string`, `number`, `integer`, `boolean`, `object`, `array`, or `null`). A custom type such as `"money"` fails validation, and the error details report that the value `is not valid under any of the given schemas`.
* 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: Fields the model cannot extract (strict mode)

This error occurs when [`strict`](./extract-input#options) is `true` and the schema contains one or more fields the model cannot extract. When `strict` is `false` (default), those fields are skipped and extraction continues.

**What to do:**

* Confirm the document actually contains the data for the fields that could not be extracted.
* Refine each field's `description` and `x-alternativeNames` to help the model locate the data. See [Field Descriptions](./ade-extract-schema-json#field-descriptions) and [Alternative Names](./ade-extract-schema-json#alternative-names).
* To skip fields that cannot be extracted instead of returning an error, set `strict` to `false`.

### Error: Schema fields not supported (strict mode)

This error occurs when [`strict`](./extract-input#options) is `true` and the schema contains keywords the extraction engine does not support. When `strict` is `false` (default), unsupported keywords are ignored and extraction continues.

**Error message:**

```
The following schema fields were not supported: {keywords}
```

**What to do:**

* Remove the listed keywords from your schema. See [Extraction Schema (JSON)](./ade-extract-schema-json) for the supported schema features.
* To ignore unsupported keywords instead of returning an error, set `strict` to `false`.

### 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: Provide exactly one Markdown source

This error occurs when your request does not include a Markdown source.

**Error message:**

```
provide exactly one of 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/parse/ade-parse) 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.

**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).

## Extract Jobs

These status codes apply to the asynchronous [Extract Jobs v2](./extract-async) endpoints.

### Create a Job

These status codes apply to `POST /v2/extract/jobs`.

| Status Code | Name                  | Description                                                          | What to Do                                                                                                                       |
| ----------- | --------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| 202         | Accepted              | The job was queued successfully. The response contains the `job_id`. | Poll `GET /v2/extract/jobs/{job_id}` to track status and retrieve the result.                                                    |
| 409         | Conflict              | A job with the same identifier already exists.                       | Retry the request.                                                                                                               |
| 422         | Unprocessable Entity  | Input validation failed.                                             | The causes and fixes match the synchronous Extract API. See [Status 422](#status-422-unprocessable-entity).                      |
| 429         | Too Many Requests     | Rate limit exceeded.                                                 | Wait before retrying. Reduce request frequency and implement exponential backoff. See [Rate Limits](./rate-limits#extract-jobs). |
| 500         | Internal Server Error | Server error while creating the job.                                 | Retry. If the issue persists, contact [support@landing.ai](mailto:support@landing.ai).                                           |

### Get a Job

These status codes apply to `GET /v2/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 `result`. When `status` is `failed`, the `error` field describes what went wrong. | Read the `status` field.                                                                                          |
| 404         | Not Found             | No job with the given ID exists for your API key.                                                                                                                | Verify the `job_id` matches the value returned when you created the job, and that you are using the same API key. |
| 500         | Internal Server Error | Server error while retrieving the job.                                                                                                                           | Retry. If the issue persists, contact [support@landing.ai](mailto:support@landing.ai).                            |

## When Are Credits Consumed?

Credits are consumed only when the API returns a 200 status code. All other responses, including errors, do not consume credits. For Extract Jobs, credits are consumed only when a job reaches the `completed` status; failed jobs do not consume credits. For more information, see [Credit Consumption](./credit-consumption).