Skip to main content

​
Exception hierarchy

StewAIError
├── ApiError
│   ├── AuthenticationError
│   └── RateLimitError
├── RunError
│   ├── RunFailedError
│   ├── RunCancelledError
│   └── RunBlockedError
└── StewAITimeoutError

​
Construction-time error

Client() raises ValueError if no API key is provided (neither api_key= nor STEWAI_API_KEY).

​
API-level errors

​
ApiError

Fields:
  • status_code: int
  • body: Any
  • message: str

​
AuthenticationError

Raised on 401/403.

​
RateLimitError

Raised on 429.
  • retry_after: str | None from Retry-After header

​
Run-level errors

Raised by runs.create(wait=True) or runs.wait(...) when terminal status is non-success.
  • RunFailedError (failed)
  • RunCancelledError (cancelled)
  • RunBlockedError (blocked)
Fields on RunError:
  • run_id: str
  • run: dict

​
Timeout

StewAITimeoutError fields:
  • run_id: str
  • timeout: float
  • last_status: str

​
Pattern example

from stewai import (
    Client,
    AuthenticationError,
    RateLimitError,
    RunFailedError,
    RunCancelledError,
    RunBlockedError,
    StewAITimeoutError,
    StewAIError,
)

client = Client(api_key="your-api-key")

try:
    run = client.runs.create(recipe_id="01JEXAMPLE00000000000000000", timeout=120)

except AuthenticationError:
    print("invalid auth")

except RateLimitError as e:
    print("rate limited", e.retry_after)

except (RunFailedError, RunCancelledError, RunBlockedError) as e:
    print("run terminal error", e.run_id)

except StewAITimeoutError as e:
    print("timed out", e.run_id, e.last_status)

except StewAIError as e:
    print("sdk error", e)

​
See also