Errors and retries

All HTTP client errors inherit from OrbitalsAIError. Catch a specific error when your application can recover differently.

from orbitalsai import (
    AuthenticationError,
    ContentTooLongError,
    InsufficientBalanceError,
    ModelWarmingError,
    OrbitalsAIError,
    TextGenerationError,
    TimeoutError,
)
 
try:
    result = client.summarize(transcript, "Hausa")
except AuthenticationError:
    disable_invalid_key()
except InsufficientBalanceError:
    notify_account_owner()
except ContentTooLongError:
    job = client.submit_text_job("summarize", transcript, "Hausa")
except ModelWarmingError as error:
    schedule_retry(error.retry_after or 120)
except TextGenerationError as error:
    record_unusable_output(str(error))
except OrbitalsAIError as error:
    report_api_failure(str(error))

Timeouts do not cancel jobs

When wait_for_text_job() raises the SDK’s TimeoutError, the backend job continues running. Retain its ID and query it later:

try:
    completed = client.wait_for_text_job(job.job_id, timeout=300)
except TimeoutError:
    save_for_later(job.job_id)

Streaming errors

Streaming has protocol-specific exceptions under orbitalsai.streaming, including ConnectionError, AuthenticationError, AudioFormatError, InsufficientCreditsError, and SessionClosedError.

Use on_error() for session failures and on_translation_failed() for a missing translation. The latter means the source transcript is still valid.

See Errors and limits for platform behavior and the API error reference for HTTP status handling.

Timeouts do not cancel jobs

Streaming errors

On this page