Skip to main content
The SDK raises standard Python exceptions. Here’s how to handle them.

​
Error Types

​
HTTP Errors

API failures raise requests.exceptions.HTTPError with the status code and server error message. 
import requests
from docent import Docent

client = Docent()

try:
    collection = client.get_collection("nonexistent-id")
except requests.exceptions.HTTPError as e:
    print(f"HTTP {e.response.status_code}: {e}")
Common HTTP status codes:
StatusMeaning
400Bad request — invalid parameters or malformed data
401Unauthorized — invalid or missing API key
403Forbidden — insufficient permissions
404Not found — collection, run, or rubric doesn’t exist
413Payload too large — reduce batch size
429Rate limited — slow down requests
500Server error — retry or contact support

​
Validation Errors

Invalid inputs raise ValueError: 
try:
    client.execute_dql("my-collection", "")  # Empty query
except ValueError as e:
    print(f"Invalid input: {e}")
Common causes:
  • Empty required fields (dql, agent_run_ids, etc.)
  • Invalid parameter values (limit <= 0, unsupported permission values)
  • Missing API key at initialization

​
Schema Validation Errors

Invalid JSON schemas raise jsonschema.ValidationError: 
import jsonschema

try:
    client.create_label_set(
        "my-collection",
        name="Test",
        label_schema={"type": "invalid_type"},
    )
except jsonschema.ValidationError as e:
    print(f"Invalid schema: {e.message}")

​
Job Failures

When using add_agent_runs(wait=True), failed background jobs raise RuntimeError: 
try:
    client.add_agent_runs(collection_id, runs, wait=True)
except RuntimeError as e:
    print(f"Job failed: {e}")

​
Retry Behavior

The SDK automatically retries on server errors (5xx) for agent run uploads (add_agent_runs), with exponential backoff (up to 3 retries by default). Client errors (4xx) are not retried. Other methods do not retry automatically.

​
Best Practices

import requests
from docent import Docent

client = Docent()

# Wrap API calls that might fail
try:
    result = client.execute_dql(collection_id, query)
    rows = client.dql_result_to_dicts(result)
except requests.exceptions.HTTPError as e:
    if e.response.status_code == 404:
        print("Collection not found")
    elif e.response.status_code == 401:
        print("Check your API key")
    else:
        raise
except ValueError as e:
    print(f"Invalid query: {e}")