Error Handling

import os
from openai import OpenAI
from solwyn import (
    BudgetExceededError,
    ConfigurationError,
    ProviderUnavailableError,
    RunStoppedError,
    Solwyn,
)

try:
    client = Solwyn(
        OpenAI(),
        api_key=os.environ["SOLWYN_API_KEY"],
        budget_mode="hard_deny",
    )
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello!"}],
    )
    print(response.choices[0].message.content)
except ConfigurationError as e:
    print(f"Bad config ({e.field}): {e.message}")
except RunStoppedError as e:
    print(f"Run {e.agent_run_id} was stopped ({e.source}: {e.reason})")
except BudgetExceededError as e:
    print(f"Budget blocked: ${e.current_usage:.2f} / ${e.budget_limit:.2f}")
except ProviderUnavailableError as e:
    print(f"No provider could be dispatched. Candidates: {e.attempted}")
finally:
    client.close()

Solwyn SDK errors fall into three categories: pre-flight errors that prevent construction, errors raised during calls when the SDK cannot or must not proceed, and silent errors that are logged but never raised.

Error categories

1. Pre-flight errors (construction time)

These are raised when Solwyn() or AsyncSolwyn() is constructed with invalid configuration:

from openai import OpenAI
from solwyn import ConfigurationError, Solwyn

try:
    client = Solwyn(
        OpenAI(),
        api_key="not_a_valid_key",
    )
except ConfigurationError as e:
    print(f"Field: {e.field}")    # "api_key"
    print(f"Error: {e.message}")  # format validation message

ConfigurationError is raised immediately -- no LLM call is attempted. Constructing a SolwynConfig directly raises pydantic's ValidationError instead; the client wrapper is what converts it.

2. Call-time errors

These are raised during LLM calls when the SDK cannot proceed:

The two translation errors are raised before any network call and abort the whole failover chain. They carry structural labels only (source, target, feature / model, provider) — never prompt content. See Provider Failover.

ConfigurationError is also raised at call time in a few deliberate cases, each one preventing a call that would bypass metering:

• calling invoke_model, invoke_model_with_response_stream, or start_async_invoke on a Bedrock-wrapped client (field is the method name) — use converse() / converse_stream(), or the unwrapped boto3 client for deliberately untracked calls. See Amazon Bedrock.
• a metered Responses call with background=True (field="background"), a streaming responses.parse (field="stream"), or an extra_body that overrides model, input, instructions, max_output_tokens, or stream (field="extra_body"). See The Responses API.

Provider errors from the underlying SDK (e.g. openai.APIError, anthropic.APIError, botocore.exceptions.ClientError) are not caught by Solwyn. When the failover chain cannot recover, they propagate directly to your code, just as they would without the wrapper.

3. Silent errors (logged only)

These are internal errors that the SDK handles gracefully without raising:

Silent errors are logged via the standard Python logging module at the WARNING level. Enable logging to see them:

import logging
logging.basicConfig(level=logging.WARNING)

Exception hierarchy

All Solwyn exceptions inherit from SolwynError:

SolwynError (base -- catch this to handle any SDK error)
  +-- BudgetExceededError
  +-- RunStoppedError
  +-- ProviderUnavailableError
  +-- ConfigurationError
  +-- UntranslatableRequestError
  +-- UntranslatableModelError
  +-- UnsupportedSurfaceError
  +-- UntrackedSpendSurfaceError   (also an AttributeError)
  +-- CoverageMismatchError

UntrackedSpendSurfaceError inherits from AttributeError as well, so hasattr(client.moderations, "create") and getattr(client.moderations, "create", None) keep working as feature probes under strict mode (probe the leaf — client.moderations itself is a namespace and is never refused). SurfaceInspectionError (raised when coverage() cannot observe part of a client) and the SolwynTagsClampedWarning warning class are exported too but sit outside this tree — the first is a RuntimeError, the second a UserWarning.

SolwynError is exported from the top-level package alongside its subclasses. Use it when you want a single except clause for any Solwyn error:

from solwyn import SolwynError

try:
    response = client.chat.completions.create(...)
except SolwynError:
    # catches all Solwyn-raised errors
    ...

Order matters when you catch both RunStoppedError and BudgetExceededError: neither inherits from the other, so either order works, but a bare except SolwynError placed first will take both.

fail_open behavior

The fail_open setting controls what happens when Solwyn Cloud is unreachable:

Two decisions never fail open, whatever this setting says: a run stop the SDK has already received (server or local) keeps raising RunStoppedError through the outage, and a sticky hard deny on record for the run or project period is preserved rather than forgotten. An outage only affects calls that have no authoritative verdict yet. See Run control and When Solwyn Cloud is unreachable.

import os
from openai import OpenAI
from solwyn import Solwyn

# Default: fail_open=True -- calls always proceed
client = Solwyn(
    OpenAI(),
    api_key=os.environ["SOLWYN_API_KEY"],
)

# Strict: fail_open=False -- enforce locally when cloud is down
client = Solwyn(
    OpenAI(),
    api_key=os.environ["SOLWYN_API_KEY"],
    fail_open=False,
    budget_mode="hard_deny",
)

Testing error handling

SDK v0.6.0+: every path above can be exercised without a network. solwyn.testing.FakeControlPlane scripts denials (model="solwyn-test/deny"), outages (plane.outage()), operator kills (plane.stop_run(run_id)), ingest rejections, and lease refusals against the real SDK wire models, and records what the SDK sent. The fail-open recipe asserts on the budget check failed warning through caplog. See Testing budget enforcement.

Exception attribute reference

Every exception's attributes — budget_limit, current_usage, budget_period, attempted, field, the RunStoppedError agent_run_id / reason / source, the UntrackedSpendSurfaceError surface / token / kind, the translation-error source/target/feature/model/provider labels, and the rest — live in one place: Exceptions. That reference is the single source for what each exception carries.