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

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

Use this section to troubleshoot issues encountered when calling the [Ground API](./ground) (`/v2/ground`).

## Error Response Format

Every error from the v2 APIs returns a JSON body with two fields:

```json theme={null}
{
  "code": "validation_error",
  "message": "structure: Field required"
}
```

The `code` field is a stable identifier you can branch on, such as `validation_error` or `not_implemented`. The `message` field is a human-readable description; treat its exact wording as variable. The error messages quoted on this page are `message` values.

## 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).            |
| 502         | Bad Gateway         | A transient infrastructure error interrupted the request. | Retry with exponential backoff.                                                                                 |
| 503         | Service Unavailable | The service is temporarily unavailable.                   | Retry with exponential backoff. If the error persists, contact [support@landing.ai](mailto:support@landing.ai). |

## Ground Status Codes

| Status Code | Name                  | Description                                                                                                                                                   | What to Do                                                                                                                                                                              |
| ----------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200         | Success               | Grounding completed successfully.                                                                                                                             | A `200` response can still carry wrong locations, because a mismatched pair is not an error. See [The Locations Point at the Wrong Content](#the-locations-point-at-the-wrong-content). |
| 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).                                                                                                  |
| 501         | Not Implemented       | Your organization has Zero Data Retention enabled.                                                                                                            | See [Status 501: Not Implemented](#status-501-not-implemented).                                                                                                                         |
| 504         | Gateway Timeout       | Request processing exceeded the timeout limit (475 seconds). Grounding normally completes well within that limit, so this is rare even for very large inputs. | Retry. If the error persists, contact [support@landing.ai](mailto:support@landing.ai).                                                                                                  |

## Status 422: Unprocessable Entity

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

### Error: Field Required

This error occurs when the request is missing `extraction_metadata` or `structure`. Both fields are required.

**Error message:**

```
structure: Field required
```

or

```
extraction_metadata: Field required
```

**What to do:**

* Include both fields in the request body: the `extraction_metadata` object from an [Extract response](./extract-response#per-field-metadata-extraction_metadata) and the `structure` object from the matching [Parse response](./parse-response#structure-pages-and-blocks).
* If you send multipart form data, confirm each field's value is a JSON-serialized object. An empty or unparseable value also fails validation.

## Status 501: Not Implemented

This error occurs when your organization has [Zero Data Retention](../ade/zdr) (ZDR) enabled. The Ground API is not available for ZDR-enabled organizations, because the request carries extracted document content in `extraction_metadata`.

**What to do:**

* Compute grounding client-side instead: every block in the Parse response's `structure` carries its own `grounding.range`, so you can overlap each field's `ranges` against the blocks yourself. See [Grounding with Ranges](./extract-response#grounding-with-ranges) and [Grounding: Where Things Are](./parse-response#grounding-where-things-are).
* If your organization does not need ZDR, you can ask to turn it off by contacting [support@landing.ai](mailto:support@landing.ai).

## The Locations Point at the Wrong Content

Grounding returned `200` and every field has blocks, but the boxes land on the wrong part of the page, or one value in a batch is highlighted somewhere unrelated.

This is what a mismatched `extraction_metadata` and `structure` normally look like. The ranges are still valid numbers, so they overlap whatever blocks sit at those offsets in the `structure` you sent. Two parses of the same document produce similar offsets, so most locations come back correct and only some are wrong. Nothing in the response marks the difference.

**What to do:**

* Verify the pairing rather than judging it by eye, by comparing the Extract response's `metadata.doc_id` with the Parse response's `metadata.job_id`. See [Pair the Extraction with Its Own Parse](./ground#pair-the-extraction-with-its-own-parse).
* If you re-parse a document, re-run the extraction too. Block ranges shift between parses, even of the same file, so an old extraction cannot be grounded against a new `structure`.
* If the pair checks out, confirm you did not edit the `markdown` between the Parse call and the Extract call. Inserting or removing characters shifts every offset after the edit.

## Every Field Returns an Empty Array

Grounding returned `200`, but every field's grounding is `[]`. Valid ranges that overlap no block almost always mean the two inputs are from different parses, and far enough apart that no offsets overlap at all: the `extraction_metadata` offsets index a different Markdown string than the one the `structure` describes.

**What to do:**

* Work through [The Locations Point at the Wrong Content](#the-locations-point-at-the-wrong-content). An empty result has the same cause as a wrong one, and the same fix.
* Check that the `structure` is the whole tree from the Parse response, not a single page or a trimmed subtree. A structure covering only part of the document has no blocks at most offsets.

## A Field Returns Null Instead of Blocks

A field whose grounding is `null` is not an error. The field's `ranges` was `null` in the `extraction_metadata`, so nothing in the document was quoted for it. Check the field's value in the Extract response to tell the two causes apart:

* The value is present. The model synthesized it (for example, a summary or an inferred flag) rather than quoting it, so there is no source passage to point to.
* The value is `null`. The model did not find the field in the document at all.

**What to do:**

* If a synthesized field should have been quoted, refine its schema `description` so the model extracts a literal value. See [Extraction Schema (JSON)](./ade-extract-schema-json).
* Handle `null` in your rendering code: show the value without a source highlight, or show the field as not found.

## When Are Credits Consumed?

The Ground API never consumes credits. Every call is still recorded in your usage history. For more information, see [Credit Consumption](./credit-consumption#ground).