Errors

The API returns a consistent error envelope for all error responses.

Error format

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "Document not found"
  }
}

Status codes

Status	Error Type	When it happens
400	invalid_request_error	Malformed request body or invalid parameters
401	authentication_error	Missing or invalid Authorization: Bearer token
403	permission_error	API key does not have access to the requested resource
404	not_found_error	Document, job, or schema not found
408	request_timeout_error	Request took too long to process
409	conflict_error	Resource already exists or conflicting operation
413	request_too_large	File exceeds the 100 MB upload limit
422	unprocessable_entity_error	Valid request but the operation cannot be performed
429	rate_limit_error	Too many requests — back off and retry
500	api_error	Unexpected server error

Handling errors

response = requests.post(url, headers=headers, files=files)

if response.status_code >= 400:
    error = response.json()["error"]
    print(f"{error['type']}: {error['message']}")

tipp

For 429 responses, wait before retrying. The error message includes the recommended wait time.

---

Next steps

• Quick Start — Upload your first document
• API Reference — Full endpoint documentation