[FEAT] Improve Python SDK error messages for missing or invalid configuration

[TheEleventhAvatar]

When required configuration values (such as server URL, API key, or environment
variables) are missing or invalid, the Python SDK can currently fail with generic
exceptions or low-context errors.

This can be confusing for new users and slows down debugging, as it’s not always
clear which configuration value is missing or how to fix the issue.

I’d like to improve the Python SDK’s configuration validation and error messaging by
explicitly checking for required configuration at initialization time and raising
clear, actionable errors that explain what’s missing and how to resolve it (for
example, which environment variable or argument is required).

This would improve the onboarding experience, reduce common setup issues, and provide
faster feedback without changing any existing SDK behavior for correctly configured
clients.

[mrkaye97]

hey @TheEleventhAvatar - there's a bigger issue at play here IMO, which is that in 95% of cases, you really only need to set the token (generally via env var) and any other optional config like healthcheck config, etc., but you don't need to set any of the server url, host port, etc. IMO, making that clearer is a good idea, but it may be that the best we can do for now, without breaking changes, would be to improve the documentation here.

[TheEleventhAvatar]

That makes sense, thanks for the clarification — I hadn’t fully appreciated that in
most cases only the token needs to be set and the server URL / host config is largely
optional.

I agree that making this clearer would reduce a lot of confusion for new users. I’m
happy to start by improving the documentation to explicitly call out the minimal
required configuration (token-only) vs optional overrides like server URL and
healthcheck config.

Separately, if it’s acceptable without introducing breaking changes, I could also look
at improving error messages in cases where optional config is provided but invalid
(e.g. malformed URLs), while keeping defaults untouched.

Let me know if that direction sounds reasonable — happy to align with whatever you
think is the right starting point.

[mrkaye97]

Sure, great! We have lots of improvements to our documentation that we need, in particular. And I'm also in favor of improving error messages to be more helpful. Happy to take a look if you give it a shot!

[TheEleventhAvatar]

Sounds great — thanks!

I’ll start by putting together a docs PR that clearly outlines the minimal required
configuration (token-only) vs optional overrides, and also look for places where we can
call out common misconfigurations more explicitly.

In parallel, I’ll take a first pass at improving a few high-impact error messages to
make failures easier to understand without changing existing behavior. I’ll keep the
scope tight and break things up so it’s easy to review.

I’ll share the PR(s) shortly — appreciate you taking a look.

[mrkaye97]

Sounds good! Thanks :)

[TheEleventhAvatar]

PR #3017