Python SDK

Error Handling

Typed exceptions for every failure mode — no string parsing required.

The SDK raises typed exceptions so you can handle specific failure scenarios cleanly. All exceptions inherit from GuidedMindError, so a single broad except is always available as a fallback.

Exception Hierarchy

GuidedMindError
├── APIError                  # Base for all HTTP errors (has .status_code)
│   ├── AuthenticationError   # 401 / 403
│   ├── NotFoundError         # 404
│   ├── ValidationError       # 422
│   └── RateLimitError        # 429 (raised only after all retries exhausted)
└── ConfigurationError        # Bad client config (missing key, HTTP base URL, etc.)

Catching Exceptions

from guidedmind import (
    Client,
    GuidedMindError,
    AuthenticationError,
    RateLimitError,
    NotFoundError,
    ValidationError,
    APIError,
)
 
client = Client()
 
try:
    response = client.search(query="What is RAG?")
 
except AuthenticationError:
    # 401 or 403 — key is invalid, expired, or lacks permission
    print("Check your GUIDEDMIND_API_KEY")
 
except RateLimitError as e:
    # 429 — SDK already retried max_retries times before raising
    print(f"Rate limit exhausted. Retry after: {e.retry_after}s")
 
except NotFoundError as e:
    # 404 — agent, document, or session does not exist
    print(f"Resource not found: {e}")
 
except ValidationError as e:
    # 422 — invalid parameters (e.g. threshold > 1.0)
    print(f"Bad request: {e.detail}")
 
except APIError as e:
    # Any other HTTP 4xx / 5xx
    print(f"API error {e.status_code}: {e}")
 
except GuidedMindError as e:
    # Catch-all for SDK errors (includes ConfigurationError)
    print(f"SDK error: {e}")

Automatic Retries

The SDK automatically retries on 429 and 5xx responses using exponential backoff with jitter. RateLimitError and server errors are only raised to your code if all retry attempts are exhausted.

Attempt	Delay
1	immediate
2	~1s
3	~2s
4	~4s

Configure the retry count at client initialisation:

# More aggressive retries for critical paths
client = Client(max_retries=5)
 
# Disable retries (fail immediately on first error)
client = Client(max_retries=0)

Exception Properties

# APIError properties
e.status_code   # int  — HTTP status code (400, 401, 404, 422, 429, 500…)
e.message       # str  — human-readable description
e.request_id    # str  — trace ID for support enquiries
 
# RateLimitError additional property
e.retry_after   # int | None — seconds until you can retry (from Retry-After header)
 
# ValidationError additional property
e.detail        # list[dict] — Pydantic validation error details

Logging Errors

The SDK uses Python's standard logging module. Enable debug logging to see full request/response traces (API keys are always redacted automatically):

import logging
 
logging.basicConfig(
    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
    level=logging.DEBUG,
)
 
# Scope to just the SDK
logging.getLogger("guidedmind").setLevel(logging.DEBUG)

Never log exception objects with str(e) and then forward those strings to an external service without sanitising first. The SDK redacts keys inside its own log output, but your own exception handlers may inadvertently capture them if you format raw request/response data.

← PreviousFramework Integrations Next →Security