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

# Exceptions

> Error hierarchy and exception reference

All Vrin SDK exceptions inherit from `VRINError`. You can catch `VRINError` to handle any SDK error, or catch specific subclasses for fine-grained control.

## Exception hierarchy

```
VRINError
  +-- AuthenticationError
  +-- RateLimitError
  +-- ValidationError
  +-- ServiceUnavailableError
  +-- JobFailedError
  +-- TimeoutError
  +-- InsufficientCoverageError
  +-- StreamingError
```

## VRINError

Base exception for all SDK errors.

```python theme={null}
from vrin import VRINError

try:
    result = client.query("What is ACME's revenue?")
except VRINError as e:
    print(f"Vrin error: {e}")
```

## AuthenticationError

Raised when authentication fails (HTTP 401). The API key is invalid, expired, or missing.

```python theme={null}
from vrin import AuthenticationError

try:
    client = VRINClient(api_key="invalid_key")
    client.query("test")
except AuthenticationError:
    print("Invalid API key")
```

## RateLimitError

Raised when rate limits are exceeded (HTTP 429). Back off and retry after a delay.

```python theme={null}
from vrin import RateLimitError

try:
    result = client.query("test")
except RateLimitError:
    print("Rate limit hit -- wait before retrying")
```

## ValidationError

Raised when input validation fails. Check the error message for details.

## ServiceUnavailableError

Raised when the Vrin service is unavailable (HTTP 5xx). The client retries automatically based on `max_retries` before raising this exception.

## JobFailedError

Raised by `wait_for_job()` when a processing job fails.

```python theme={null}
from vrin import JobFailedError

try:
    result = client.insert("content", title="Test")
except JobFailedError as e:
    print(f"Job failed: {e}")
```

## TimeoutError

Raised when an operation exceeds its timeout. For async jobs, use `get_job_status()` to check if the job is still running.

```python theme={null}
from vrin import TimeoutError

try:
    result = client.insert("very long document...", max_wait=60.0)
except TimeoutError:
    print("Job still processing -- check status manually")
```

<Note>
  This is `vrin.TimeoutError`, not Python's built-in `TimeoutError`. Import it from `vrin` to avoid confusion.
</Note>

## InsufficientCoverageError

Raised when the knowledge base has zero coverage for a query. This means no relevant entities or facts were found.

## StreamingError

Raised during SSE streaming when the backend sends an error event.

```python theme={null}
from vrin import StreamingError

try:
    for token in client.query("test", stream=True):
        print(token, end="")
except StreamingError as e:
    print(f"Stream error: {e}")
```

## Error handling patterns

See the [Error Handling guide](/guides/error-handling) for recommended patterns including retry logic and graceful degradation.