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

Wrong API host

Every error in the table above arrives in the envelope shown at the top of this page. A response that is not in that envelope did not come from the API at all — it came from something in front of it, which almost always means the request went to the wrong host or the /v1 prefix is missing.

What you get back	What it means
404 with {"message": "no Route matched with those values"}	Reached the API gateway, but no route matched. Usually a missing /v1 prefix, or a typo such as /V1 — paths are case-sensitive.
405 Method Not Allowed on a POST	The host is serving the web app, not the API. A static web server rejects POST.
200 with HTML instead of JSON	Same cause: the web app host returned its page for an unknown path. A GET probe against the wrong host can look successful — check the response body, not just the status.

In all three cases the fix is the base URL, not the API key: the key was never checked, because the request never reached the API. Confirm you are using the API host issued with your key, followed by /v1.

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