Error Handling

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:

Status	Meaning
400	Bad request — invalid parameters or malformed data
401	Unauthorized — invalid or missing API key
403	Forbidden — insufficient permissions
404	Not found — collection, run, or rubric doesn’t exist
413	Payload too large — reduce batch size
429	Rate limited — slow down requests
500	Server 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. The exception message is the server-provided error_message from the job status when available, and falls back to "Job was canceled" otherwise:

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}")

Getting Started

Collections

Agent Runs

DQL

Feedback & Labels

More

Legacy

Error Handling

Error Types

HTTP Errors

Validation Errors

Schema Validation Errors

Job Failures

Retry Behavior

Best Practices

​Error Types

​HTTP Errors

​Validation Errors

​Schema Validation Errors

​Job Failures

​Retry Behavior

​Best Practices

Error Types

HTTP Errors

Validation Errors

Schema Validation Errors

Job Failures

Retry Behavior

Best Practices