Exceptions

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.

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.

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.

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.

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.

from vrin import TimeoutError

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

This is vrin.TimeoutError, not Python’s built-in TimeoutError. Import it from vrin to avoid confusion.

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.

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 for recommended patterns including retry logic and graceful degradation.

Get Started

MCP Server

CLI

Python SDK

TypeScript SDK

Concepts

Guides

Exception hierarchy

VRINError

AuthenticationError

RateLimitError

ValidationError

ServiceUnavailableError

JobFailedError

TimeoutError

InsufficientCoverageError

StreamingError

Error handling patterns

​Exception hierarchy

​VRINError

​AuthenticationError

​RateLimitError

​ValidationError

​ServiceUnavailableError

​JobFailedError

​TimeoutError

​InsufficientCoverageError

​StreamingError

​Error handling patterns

Exception hierarchy

VRINError

AuthenticationError

RateLimitError

ValidationError

ServiceUnavailableError

JobFailedError

TimeoutError

InsufficientCoverageError

StreamingError

Error handling patterns