Skip to main content
The Lyzr ADK provides a hierarchy of exceptions to help you handle errors gracefully. All exceptions inherit from LyzrError.

​
Quick Start

from lyzr import Studio
from lyzr.exceptions import (
    LyzrError,
    AuthenticationError,
    ValidationError,
    NotFoundError,
    RateLimitError,
    APIError,
    TimeoutError,
    InvalidResponseError,
    ToolNotFoundError
)

studio = Studio(api_key="your-api-key")

try:
    agent = studio.get_agent("invalid_id")
except NotFoundError:
    print("Agent not found")
except LyzrError as e:
    print(f"ADK error: {e.message}")

​
Exception Hierarchy

LyzrError (base)
├── AuthenticationError    # Invalid/missing API key
├── ValidationError        # Invalid input parameters
├── NotFoundError          # Resource not found (404)
├── RateLimitError         # Rate limit exceeded (429)
├── APIError               # General API errors
├── TimeoutError           # Request timeout
├── InvalidResponseError   # Response parsing/validation failed
└── ToolNotFoundError      # Local tool not found

​
LyzrError

Base exception class for all ADK errors. 
class LyzrError(Exception):
    message: str                    # Error message
    status_code: int | None         # HTTP status code (if applicable)
    response: dict | None           # Raw API response (if available)

​
Properties

PropertyTypeDescription
messagestrHuman-readable error message
status_codeint | NoneHTTP status code
responsedict | NoneRaw API response

​
Example

try:
    response = agent.run("Hello")
except LyzrError as e:
    print(f"Error: {e.message}")
    if e.status_code:
        print(f"Status: {e.status_code}")
    if e.response:
        print(f"Response: {e.response}")

​
AuthenticationError

Raised when the API key is invalid, missing, or expired. 
from lyzr.exceptions import AuthenticationError

try:
    studio = Studio(api_key="invalid-key")
    agent = studio.create_agent(...)
except AuthenticationError:
    print("Invalid API key. Please check your credentials.")

​
Common Causes

  • API key is incorrect
  • API key is missing (not in env var or parameter)
  • API key has been revoked
  • API key doesn’t have required permissions

​
ValidationError

Raised when input parameters fail validation. 
from lyzr.exceptions import ValidationError

try:
    agent = studio.create_agent(
        name="",  # Empty name - invalid
        provider="gpt-4o",
        temperature=5.0  # Out of range - invalid
    )
except ValidationError as e:
    print(f"Invalid input: {e.message}")

​
Common Causes

  • Empty or invalid agent name
  • Temperature out of range (0.0-2.0)
  • Top_p out of range (0.0-1.0)
  • Invalid provider/model combination
  • Missing required parameters

​
NotFoundError

Raised when a requested resource doesn’t exist (HTTP 404). 
from lyzr.exceptions import NotFoundError

try:
    agent = studio.get_agent("nonexistent_agent_id")
except NotFoundError:
    print("Agent not found. It may have been deleted.")

​
Common Causes

  • Agent ID doesn’t exist
  • Knowledge base ID doesn’t exist
  • Context ID doesn’t exist
  • RAI policy ID doesn’t exist
  • Resource was deleted

​
RateLimitError

Raised when API rate limits are exceeded (HTTP 429). 
from lyzr.exceptions import RateLimitError
import time

def run_with_retry(agent, message, max_retries=3):
    for attempt in range(max_retries):
        try:
            return agent.run(message)
        except RateLimitError:
            if attempt < max_retries - 1:
                wait_time = 2 ** attempt  # Exponential backoff
                print(f"Rate limited. Waiting {wait_time}s...")
                time.sleep(wait_time)
            else:
                raise

response = run_with_retry(agent, "Hello")

​
Common Causes

  • Too many requests in a short period
  • Account quota exceeded
  • Concurrent request limit reached

​
APIError

Raised for general API errors not covered by other exceptions. 
from lyzr.exceptions import APIError

try:
    response = agent.run("Process this request")
except APIError as e:
    print(f"API error: {e.message}")
    print(f"Status code: {e.status_code}")

​
Common Causes

  • Server-side errors (5xx)
  • Network issues
  • Invalid request format
  • Service unavailable

​
TimeoutError

Raised when a request takes too long to complete. 
from lyzr.exceptions import TimeoutError

try:
    # Long-running operation
    response = agent.run("Generate a very long document")
except TimeoutError:
    print("Request timed out. Try breaking into smaller requests.")

​
Common Causes

  • Complex queries taking too long
  • Large document processing
  • Network latency
  • Server under heavy load

​
InvalidResponseError

Raised when the API response cannot be parsed or validated. 
from lyzr.exceptions import InvalidResponseError

try:
    result = agent.run("Generate structured data")
except InvalidResponseError as e:
    print(f"Failed to parse response: {e.message}")
    if e.validation_error:
        print(f"Validation error: {e.validation_error}")
    if e.response:
        print(f"Raw response: {e.response}")

​
Properties

PropertyTypeDescription
messagestrError message
status_codeint | NoneHTTP status code
responseAny | NoneRaw response data
validation_errorAny | NonePydantic validation error

​
Common Causes

  • Structured output doesn’t match Pydantic model
  • Malformed JSON in response
  • Unexpected response format
  • Model returned invalid data

​
ToolNotFoundError

Raised when a local tool is called but not registered. 
from lyzr.exceptions import ToolNotFoundError

try:
    # Agent tries to call a tool that wasn't added
    response = agent.run("Use the missing_tool")
except ToolNotFoundError as e:
    print(f"Tool not found: {e.message}")

​
Common Causes

  • Tool function not added with agent.add_tool()
  • Tool name mismatch
  • Tool was removed but still referenced

​
Error Handling Patterns

​
Comprehensive Handler

from lyzr.exceptions import (
    LyzrError,
    AuthenticationError,
    ValidationError,
    NotFoundError,
    RateLimitError,
    APIError,
    TimeoutError,
    InvalidResponseError,
    ToolNotFoundError
)

def safe_agent_run(agent, message):
    """Run agent with comprehensive error handling"""
    try:
        return agent.run(message)

    except AuthenticationError:
        print("Authentication failed. Check your API key.")
        return None

    except ValidationError as e:
        print(f"Invalid input: {e.message}")
        return None

    except NotFoundError:
        print("Agent not found.")
        return None

    except RateLimitError:
        print("Rate limit exceeded. Please wait and retry.")
        return None

    except TimeoutError:
        print("Request timed out.")
        return None

    except InvalidResponseError as e:
        print(f"Invalid response: {e.message}")
        return None

    except ToolNotFoundError as e:
        print(f"Tool error: {e.message}")
        return None

    except APIError as e:
        print(f"API error ({e.status_code}): {e.message}")
        return None

    except LyzrError as e:
        print(f"ADK error: {e.message}")
        return None

​
Retry with Backoff

import time
from lyzr.exceptions import RateLimitError, TimeoutError, APIError

def run_with_retry(agent, message, max_retries=3):
    """Run with exponential backoff retry"""
    last_error = None

    for attempt in range(max_retries):
        try:
            return agent.run(message)

        except (RateLimitError, TimeoutError) as e:
            last_error = e
            wait_time = 2 ** attempt
            print(f"Attempt {attempt + 1} failed. Retrying in {wait_time}s...")
            time.sleep(wait_time)

        except APIError as e:
            if e.status_code and e.status_code >= 500:
                # Server error - retry
                last_error = e
                wait_time = 2 ** attempt
                print(f"Server error. Retrying in {wait_time}s...")
                time.sleep(wait_time)
            else:
                # Client error - don't retry
                raise

    raise last_error

​
Logging Errors

import logging
from lyzr.exceptions import LyzrError

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def run_with_logging(agent, message):
    """Run agent with error logging"""
    try:
        return agent.run(message)

    except LyzrError as e:
        logger.error(
            "Agent error",
            extra={
                "error_type": type(e).__name__,
                "message": e.message,
                "status_code": e.status_code,
            }
        )
        raise

​
Fallback Strategy

from lyzr.exceptions import APIError, TimeoutError

def run_with_fallback(primary_agent, fallback_agent, message):
    """Try primary agent, fall back to secondary on error"""
    try:
        return primary_agent.run(message)

    except (APIError, TimeoutError) as e:
        print(f"Primary agent failed: {e.message}")
        print("Trying fallback agent...")
        return fallback_agent.run(message)