Error Handling

Error Callback

Pass an on_error callback to streams.create() to handle errors that occur during streaming:

stream = await client.streams.create(
    source=overshoot.FileSource(path="/path/to/video.mp4"),
    prompt="Describe what you see",
    model="Qwen/Qwen3.5-9B",
    on_result=lambda r: print(r.result),
    on_error=handle_error,
)

Exception Hierarchy

All SDK exceptions inherit from OvershootError:

• OvershootError -- base exception for all SDK errors
  • ApiError -- base HTTP error with status_code, request_id, details
    • AuthenticationError (401) -- invalid or missing API key
    • ValidationError (400/422) -- invalid request parameters
    • NotFoundError (404) -- resource not found
    • InsufficientCreditsError (402) -- account out of credits
    • ServerError (500+) -- server-side error
  • NetworkError -- connection or timeout error with cause
  • StreamClosedError -- operation attempted on a closed stream
  • WebSocketError -- WebSocket connection or protocol error with code

Handling Errors

def handle_error(error: Exception):
    if isinstance(error, overshoot.AuthenticationError):
        print("Invalid API key")
    elif isinstance(error, overshoot.InsufficientCreditsError):
        print("Out of credits")
    elif isinstance(error, overshoot.NetworkError):
        print("Connection lost")
    else:
        print(f"Error: {error}")

See Error Handling for conceptual details on fatal vs non-fatal errors.

Logging

Enable debug logging to see detailed SDK activity:

import logging
logging.basicConfig(level=logging.DEBUG)
logging.getLogger("overshoot").setLevel(logging.DEBUG)