Skip to main content

​
Error format

All errors return a consistent JSON shape: 
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Human-readable description of the problem"
  }
}

​
Error codes

CodeHTTP StatusDescription
BAD_REQUEST400Invalid request body or parameters
UNAUTHORIZED401Missing or invalid API key
FORBIDDEN403Valid key but not authorized for this resource
NOT_FOUND404Document or resource does not exist
CONFLICT409Resource state conflict
SCHEMA_VALIDATION_FAILED422Request was well-formed but semantically invalid
RATE_LIMITED429Too many requests - see rate limits
INTERNAL_ERROR500Unexpected server error
TIMEOUT504The operation timed out

​
Handling errors

​
Retry strategy

For transient errors (429, 500, 502, 503, 504), use exponential backoff: 
import time
import requests

def api_call_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        resp = requests.get(url, headers=headers)

        if resp.status_code == 429:
            retry_after = int(resp.headers.get("Retry-After", 5))
            time.sleep(retry_after)
            continue

        if resp.status_code >= 500:
            time.sleep(2 ** attempt)
            continue

        return resp

    raise Exception(f"Failed after {max_retries} retries")

​
Non-retryable errors

CodeAction
400Fix your request body or parameters
401Check your API key
403Verify you own the resource
404Verify the document ID exists
422Check request schema against the API reference

​
Structured output errors

The /chat/completions endpoint with response_format: { type: "json_schema" } and the MCP extract_data tool return specific error codes:
CodeHTTP StatusDescription
SCHEMA_VALIDATION_FAILED422Extracted data didn’t match your JSON schema. Check field types, required fields, and nesting.
EXTRACTION_BLOCKED422The model couldn’t extract data — document has no pages, parsing failed, or all queries returned errors.
TIMEOUT504Extraction exceeded the time limit (default 45s, MCP uses 120s). Simplify the schema or use page ranges.
DOCUMENT_NOT_FOUND404Document ID doesn’t exist or hasn’t finished processing. Check get_document_status first.

​
Example error response

{
  "error": {
    "message": "Structured output timed out",
    "type": "server_error",
    "details": { "timeoutMs": 120000 }
  }
}

​
Tips for reliable extraction

  • Keep schemas flat when possible — fewer nested objects means faster extraction
  • Use string types for financial values (e.g. "$215,938 million") rather than numbers to avoid parsing ambiguity
  • Check document status before extracting — phase: "complete" is required