Skip to main content
Use this section to troubleshoot issues encountered when calling the Ground API (/v2/ground).

​
Error Response Format

Every error from the v2 APIs returns a JSON body with two fields:
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.

​
Ground Status Codes

​
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:
or
What to do:
  • Include both fields in the request body: the extraction_metadata object from an Extract response and the structure object from the matching Parse response.
  • 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 (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 and Grounding: Where Things Are.
  • If your organization does not need ZDR, you can ask to turn it off by contacting 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.
  • 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. 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).
  • 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.