Error Handling - Ragnerock Docs

The Ragnerock SDK provides a hierarchy of typed exceptions to help you handle errors gracefully. All exceptions inherit from RagnerockError and include helpful context about what went wrong.

Error Hierarchy

RagnerockError (base class)
├── AuthenticationError  # 401/403 responses
├── NotFoundError        # 404 responses
├── ValidationError      # 422 responses
└── QueryError           # SQL query failures

Importing Exceptions

from ragnerock import (
    RagnerockError,
    AuthenticationError,
    NotFoundError,
    ValidationError,
    QueryError,
)

Error Attributes

All exceptions include these attributes:

Attribute	Type	Description
`message`	`str`	Human-readable error message
`status_code`	`int \| None`	HTTP status code from the API
`suggestion`	`str \| None`	Suggested fix for the error
`details`	`dict`	Additional structured error details

try:
    doc = session.get(Document, id="nonexistent")
except NotFoundError as e:
    print(f"Message: {e.message}")
    print(f"Status: {e.status_code}")  # 404
    print(f"Suggestion: {e.suggestion}")
    print(f"Details: {e.details}")

Exception Types

AuthenticationError

Raised when authentication fails. This typically means invalid credentials or an expired session.

from ragnerock import create_engine, Session, AuthenticationError

try:
    engine = create_engine("ragnerock://wrong@email.com:badpass@api.ragnerock.com/project")
    with Session(engine) as session:
        docs = session.list(Document).all()
except AuthenticationError as e:
    print(f"Authentication failed: {e.message}")
    # Handle: prompt for new credentials, refresh token, etc.

NotFoundError

Raised when a requested resource doesn’t exist.

from ragnerock import NotFoundError

try:
    doc = session.get(Document, id="00000000-0000-0000-0000-000000000000")
except NotFoundError as e:
    print(f"Document not found: {e.message}")
    # Handle: show user-friendly message, redirect, etc.

ValidationError

Raised when request parameters are invalid, such as missing required fields or invalid data formats.

from ragnerock import Document, ValidationError

try:
    # Missing required file_path
    doc = Document(name="Test")
    session.create(doc)
except ValidationError as e:
    print(f"Invalid request: {e.message}")
    # Handle: show validation errors to user

QueryError

Raised when a SQL query fails. Includes an additional error_code attribute for programmatic error handling.

from ragnerock import QueryError

try:
    result = session.query("SELECT * FROM nonexistent_table")
except QueryError as e:
    print(f"Query failed: {e.message}")
    print(f"Error code: {e.error_code}")
    if e.suggestion:
        print(f"Try: {e.suggestion}")

Handling Patterns

Catch All SDK Errors

Use RagnerockError to catch any SDK exception:

from ragnerock import RagnerockError

try:
    with Session(engine) as session:
        # ... operations
        pass
except RagnerockError as e:
    print(f"Ragnerock error: {e}")
    # Log error, show generic message to user

Specific Error Handling

Handle different error types appropriately:

from ragnerock import (
    create_engine,
    Session,
    Document,
    AuthenticationError,
    NotFoundError,
    ValidationError,
)

def get_document(session, doc_id):
    try:
        return session.get(Document, id=doc_id)
    except NotFoundError:
        return None  # Document doesn't exist
    except AuthenticationError:
        raise  # Re-raise to handle at higher level

def upload_document(session, file_path, name):
    try:
        doc = Document(file_path=file_path, name=name)
        session.create(doc)
        return doc
    except ValidationError as e:
        print(f"Invalid document: {e.message}")
        return None

Combining with Python’s Exception Handling

import logging
from ragnerock import RagnerockError, AuthenticationError

logger = logging.getLogger(__name__)

try:
    engine = create_engine(connection_string)
    with Session(engine) as session:
        docs = session.list(Document).all()
except AuthenticationError:
    logger.error("Invalid credentials")
    raise SystemExit("Please check your Ragnerock credentials")
except RagnerockError as e:
    logger.exception("Ragnerock API error")
    raise
except Exception as e:
    logger.exception("Unexpected error")
    raise

Error Messages

The SDK formats error messages to include available context:

try:
    # ...
except RagnerockError as e:
    print(str(e))
    # Output: "[404] Document not found (Suggestion: Check the document ID)"

The string representation includes:

Status code (if available)
Error message
Suggestion (if available)

Next Steps

Session — Learn about Session methods
Engine & Connection — Configure your connection
Resources — Understand resource types