> ## Documentation Index
> Fetch the complete documentation index at: https://docs.transluce.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> Handle errors from the Docent SDK

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.

```python theme={null}
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`:

```python theme={null}
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`:

```python theme={null}
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`:

```python theme={null}
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

```python theme={null}
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}")
```