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

> Resolve Split API errors using status codes, causes, and recommended fixes.

Use this section to troubleshoot issues encountered when calling the [Split API](https://docs.landing.ai/dpt3/split.md) (`/v1/split`).

## Common Status Codes

| Status Code | Name | Description | What to Do |
| - | - | - | - |
| 200 | Success | Split classification completed successfully. | Continue with normal operations. |
| 400 | Bad Request | The Markdown file could not be downloaded from `markdown_url`. | Review error message for specific issue. See [Status 400](#status-400-bad-request). |
| 401 | Unauthorized | Missing or invalid API key. | Check that your API key header is present and contains a valid [API key](https://docs.landing.ai/dpt3/agentic-api-key.md). |
| 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](https://docs.landing.ai/dpt3/agentic-api-key.md). Add more credits to your account. |
| 413 | Content Too Large | The request exceeds the 4 MiB size limit. | Send less Markdown per request. See [Status 413](#status-413-content-too-large). |
| 422 | Unprocessable Entity | Input validation failed. | Review your request parameters. See [Status 422](#status-422-unprocessable-entity). |
| 429 | Too Many Requests | Rate limit exceeded. | Wait before retrying. Reduce request frequency and implement exponential backoff. |
| 500 | Internal Server Error | Server error during split classification. | Retry. If the issue persists, contact [support@landing.ai](mailto:support@landing.ai). See [Status 500](#status-500-internal-server-error). |
| 504 | Gateway Timeout | Request processing exceeded the timeout limit. | Reduce markdown content size. See [Status 504](#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:**

```text theme={null}
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.
* Confirm the server hosting the file does not require authentication or block external requests. If it does, download the file and send it with the `markdown` parameter instead.

## Status 413: Content Too Large

This error occurs when the request body exceeds 4 MiB. A Markdown file at `markdown_url` larger than 4 MiB returns a 422 error instead.

**What to do:**

* Split the Markdown into smaller batches of pages and send each batch in its own request.

## Status 422: Unprocessable Entity

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

### Error: No Markdown provided

This error occurs when your request does not include the `markdown` parameter or `markdown_url` parameter, or when the values are empty.

**Error message:**

```text theme={null}
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 provide inline Markdown content, OR
* Use the `markdown_url` parameter to provide a URL to a Markdown file.

### Error: Multiple markdown files detected

This error occurs when multiple Markdown files are included in the request.

**Error message:**

```text theme={null}
Multiple markdown files detected (X). Please provide only one document file.
```

**What to do:**

Send only one Markdown file per request.

### Error: Invalid file provided

This error occurs when the file you send is not UTF-8 encoded text, such as a PDF, DOCX, or image file. An empty file returns the message `File is empty.`

**Error message:**

```text theme={null}
Invalid file provided
```

**What to do:**

* If you have a PDF, DOCX, or other document format, use the [Parse API](https://docs.landing.ai/dpt3/parse.md) to convert your document to Markdown first, then pass the `markdown` field of the parse response to the split endpoint.
* Ensure your file contains UTF-8 encoded Markdown content.

### Error: Input too large

This error occurs when the Markdown contains more than 400 pages.

**Error message:**

```text theme={null}
Input too large: {pages} pages exceeds the 400-page limit. Split the document into smaller batches.
```

**What to do:**

* Split the Markdown into batches of 400 pages or fewer and send each batch in its own request.

### Error: split\_class must contain at most 19 split classification names

This error occurs when you provide more than 19 Split Types in the `split_class` parameter.

**Error message:**

```text theme={null}
split_class must contain at most 19 split classification names
```

**What to do:**

* Reduce the number of Split Types to 19 or fewer.
* Consider combining similar Split Types or removing less important ones.
* For more information, see [Split Types](https://docs.landing.ai/dpt3/split.md#split-types).

### Error: Unknown model version

This error occurs when the `model` parameter names a version that does not exist. The error message lists the available versions.

**What to do:**

* Omit `model` to use the latest version, or pass one of the versions the error message lists.

## Status 500: Internal Server Error

This error indicates an unexpected server error occurred during split classification.

**Error message:**

```text theme={null}
Internal Server Error
```

**What to do:**

* Retry the request.
* Verify your [Split Rules](https://docs.landing.ai/dpt3/split.md#split-rules) are properly formatted with valid Split Type names, descriptions, and identifiers.
* Check that your Markdown content is valid and properly formatted.
* If the error persists, contact [support@landing.ai](mailto:support@landing.ai).

## Status 504: Gateway Timeout

This error occurs when split classification does not finish within the 475-second limit for synchronous requests.

**Error message:**

```text theme={null}
v1-split did not complete within 475s
```

**What to do:**

* Reduce the size of your Markdown document.
* If processing a very large document, send its pages in smaller batches.
* If the error persists, contact [support@landing.ai](mailto:support@landing.ai).

## Best Practices for Avoiding Errors

* **Use parsed Markdown**: Always pass Markdown content that has been generated by the [Parse API](https://docs.landing.ai/dpt3/parse.md). The split endpoint expects structured Markdown with the specific format produced by the Parse API, including the `<!-- PAGE BREAK -->` markers between pages.
* **Define clear Split Rules**: Provide detailed descriptions for each Split Type to help the model accurately classify your document sections. For guidance, see [Split Rules](https://docs.landing.ai/dpt3/split.md#split-rules).
* **Use appropriate identifiers**: Only specify identifiers when your document contains multiple instances of the same Split Type that need to be separated. For guidance, see [Identifiers](https://docs.landing.ai/dpt3/split.md#identifiers-optional).

## When Are Credits Consumed?

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.