Troubleshoot Extraction

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

Error Response Format

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

{
  "code": "validation_error",
  "message": "schema: Field required"
}

The code field is a stable identifier you can branch on, such as validation_error, unknown_model_version, invalid_url, invalid_api_key, or rate_limit_exceeded. 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.
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. 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.
502	Bad Gateway	A transient infrastructure error interrupted the request.	Retry with exponential backoff. A synchronous request that fails to deliver a result is not billed.
503	Service Unavailable	The service is temporarily unavailable.	Retry with exponential backoff. If the error persists, contact support@landing.ai.

Status Codes

Status Code	Name	Description	What to Do
200	Success	Extraction completed successfully.	Continue with normal operations.
206	Partial Content	The extraction completed, but not cleanly.	Review the `warnings` and `schema_violation_error` fields. See Status 206: Partial Success.
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, including an unknown model version, an unusable `markdown_url`, or an invalid schema.	Review your request parameters. See Status 422: Unprocessable Entity.
500	Internal Server Error	Server error during processing.	Retry. If the issue persists, contact support@landing.ai. See Status 500: Internal Server Error.
504	Gateway Timeout	Request processing exceeded the timeout limit (475 seconds).	Reduce document size or simplify the extraction schema. See Status 504: Gateway Timeout.

Status 206: Partial Success

This status code indicates the extraction completed but not cleanly. The response body has the normal success shape, plus one or both of these signals:

The schema_violation_error field is set when options.strict is false and the schema contained fields the model could not extract. The extraction is partial: unsupported fields were skipped.
The warnings array lists non-fatal warnings emitted during extraction.

What to do:

Review the flagged fields and adjust your schema, or set options.strict to true to fail the request with a 422 error instead. See Schema Fields Not Supported (Strict Mode).
For Extract Jobs, the poll response stays HTTP 200; check warnings and schema_violation_error inside result instead of relying on the status code.

Status 422: Unprocessable Entity

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

Error: markdown_url Fetch Failed

This error occurs when the Markdown cannot be fetched from the provided markdown_url. The URL is validated and fetched when you submit the request, so an unusable URL fails immediately, before any processing starts. Error message:

Failed to fetch markdown_url: HTTP 404

Failed to fetch markdown_url: request timed out

Failed to fetch markdown_url: connection failed

What to do:

Verify the URL is publicly accessible and serves the Markdown directly. A URL that responds with a redirect is rejected; supply the final URL.
If the URL is presigned, confirm it has not expired.

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). 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: Unknown Extract Version

This error occurs when an unsupported model version is specified. The error code is unknown_model_version. Error message:

Unknown extract version '{version}'. Valid versions: {versions} (or extract-latest).

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.

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) 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:

{
  "type": "object",
  "properties": {
    "invoice_number": {
      "type": "string",
      "description": "Invoice number"
    }
  }
}

Incorrect:

{
  "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:

{
  "type": "object",
  "properties": {
    "invoice_number": {"type": "string"},
    "vendor_name": {"type": "string"},
    "total": {"type": "number"}
  }
}

Incorrect:

["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).

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 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 and 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 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) 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 to convert your document to Markdown first.
Ensure your file has a .md extension and contains valid UTF-8 encoded Markdown content.

Error: service_tier Is Only Valid on Extract Jobs

This error occurs when a request to the synchronous Extract endpoint (POST /v2/extract) includes the service_tier parameter. Service tiers only apply to asynchronous endpoints, like Extract Jobs. The parameter is rejected even when its value is empty. Error message:

service_tier (or its deprecated alias priority) is only valid on the async POST /v2/extract/jobs route; sync runs in the fast lane already

What to do:

Remove the service_tier parameter from Extract requests. Extract always runs on the priority tier. See Sync vs Async Processing.
To choose a service tier, create an Extract Job instead. See Choose a Service Tier.

Error: output_save_url Expired or Expires Too Soon

This error occurs when you create an Extract Job with an output_save_url whose presigned URL is already expired or does not stay valid long enough for the job to complete. The output is delivered when the job completes, so the URL must have at least 15 minutes of remaining validity at submission. The error code is invalid_url. Error message:

output_save_url presigned URL expired {time} ago; sign a fresh URL valid for at least {required}

output_save_url presigned URL expires in {remaining}, but this request requires at least {required} of validity (the URL must outlive the job; it is used at completion, not at submit)

What to do:

Sign a fresh presigned URL with a longer validity and create the job again. The job is rejected before processing starts, so no credits are consumed.
For Azure SAS URLs, also confirm the token grants write (w) or create (c) permission. A URL without write access is rejected with a similar 422 error.
Sign delivery URLs with long-lived credentials. A URL signed with temporary session credentials can pass this check but still fail at delivery if the session expires before the job completes.

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.

Status 504: Gateway Timeout

This error occurs when the extraction process exceeds the timeout limit (475 seconds). You are not billed for a request that times out. Error message:

v2-extract did not complete within 475s; use POST /v2/extract/jobs for long-running work

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). Update your JSON schema if needed.
Use Extract Jobs instead. Jobs are not subject to the synchronous timeout. See Sync vs Async Processing.
If the error persists, contact support@landing.ai.

Extract Jobs

These status codes apply to the asynchronous Extract Jobs v2 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.
429	Too Many Requests	Rate limit exceeded.	Wait before retrying. Reduce request frequency and implement exponential backoff. See Rate Limits.
500	Internal Server Error	Server error while creating the job.	Retry. If the issue persists, contact 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. Jobs have a maximum run time of 6 hours; a job that exceeds it fails.	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.
410	Gone	The job completed, but its result is no longer stored. The error code is `result_expired`. For when results are deleted, see Result Retention.	Submit a new job to run the extraction again.
500	Internal Server Error	Server error while retrieving the job.	Retry. If the issue persists, contact support@landing.ai.
503	Service Unavailable	The stored result could not be retrieved. The error code is `result_store_unavailable`. This is a transient condition. The result has not expired.	Retry with exponential backoff instead of re-running the job. If the error persists, contact support@landing.ai.

When Are Credits Consumed?

Credits are consumed only when the API returns a 200 or 206 status code. Error responses 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.

Get Started

Client Libraries

Parsing

Extraction

General

Security

Administration

Pricing & Credits

Troubleshoot Extraction

Error Response Format

Common Status Codes

Status Codes

Status 206: Partial Success

Status 422: Unprocessable Entity

Error: markdown_url Fetch Failed

Error: Field extraction invalid

Error: Unknown Extract Version

Error: The provided schema is not valid JSON

Error: The provided schema must have “type”: “object” for the root

Error: The provided JSON must parse to an object at the root

Error: The provided JSON object was not a valid JSON schema

Error: The provided schema contains recursive local $ref cycles

Error: Fields the model cannot extract (strict mode)

Error: Schema fields not supported (strict mode)

Error: Cannot provide both ‘markdown’ and ‘markdown_url’

Error: Provide exactly one Markdown source

Error: No markdown file or URL provided

Error: Invalid URL format

Error: Multiple Markdown files detected

Error: Unsupported format

Error: service_tier Is Only Valid on Extract Jobs

Error: output_save_url Expired or Expires Too Soon

Status 500: Internal Server Error

Status 504: Gateway Timeout

Extract Jobs

Create a Job

Get a Job

When Are Credits Consumed?

​Error Response Format

​Common Status Codes

​Status Codes

​Status 206: Partial Success

​Status 422: Unprocessable Entity

​Error: markdown_url Fetch Failed

​Error: Field extraction invalid

​Error: Unknown Extract Version

​Error: The provided schema is not valid JSON

​Error: The provided schema must have “type”: “object” for the root

​Error: The provided JSON must parse to an object at the root

​Error: The provided JSON object was not a valid JSON schema

​Error: The provided schema contains recursive local $ref cycles

​Error: Fields the model cannot extract (strict mode)

​Error: Schema fields not supported (strict mode)

​Error: Cannot provide both ‘markdown’ and ‘markdown_url’

​Error: Provide exactly one Markdown source

​Error: No markdown file or URL provided

​Error: Invalid URL format

​Error: Multiple Markdown files detected

​Error: Unsupported format

​Error: service_tier Is Only Valid on Extract Jobs

​Error: output_save_url Expired or Expires Too Soon

​Status 500: Internal Server Error

​Status 504: Gateway Timeout

​Extract Jobs

​Create a Job

​Get a Job

​When Are Credits Consumed?

Error Response Format

Common Status Codes

Status Codes

Status 206: Partial Success

Status 422: Unprocessable Entity

Error: markdown_url Fetch Failed

Error: Field extraction invalid

Error: Unknown Extract Version

Error: The provided schema is not valid JSON

Error: The provided schema must have “type”: “object” for the root

Error: The provided JSON must parse to an object at the root

Error: The provided JSON object was not a valid JSON schema

Error: The provided schema contains recursive local $ref cycles

Error: Fields the model cannot extract (strict mode)

Error: Schema fields not supported (strict mode)

Error: Cannot provide both ‘markdown’ and ‘markdown_url’

Error: Provide exactly one Markdown source

Error: No markdown file or URL provided

Error: Invalid URL format

Error: Multiple Markdown files detected

Error: Unsupported format

Error: service_tier Is Only Valid on Extract Jobs

Error: output_save_url Expired or Expires Too Soon

Status 500: Internal Server Error

Status 504: Gateway Timeout

Extract Jobs

Create a Job

Get a Job

When Are Credits Consumed?