Errors

All errors raised by the OptixLog SDK are subclasses of OptixLogError. You can catch the base class to handle all SDK errors, or catch a specific subclass to handle one case precisely.

from optixlog import (
    OptixLogError,
    AuthenticationError,
    NotFoundError,
    MultipleResultsError,
    ValidationError,
)
# CredentialsError, ConfigError, ContractError live on internal submodules:
from optixlog._credentials import CredentialsError

Exception hierarchy

Exception
└── OptixLogError
    ├── AuthenticationError
    ├── NotFoundError
    ├── MultipleResultsError
    ├── ValidationError
    └── CredentialsError      (credential resolution path)

ConfigError and ContractError are used internally by the CLI and code-generation paths (not by the Management or Pipeline APIs). They are subclasses of OptixLogError where applicable and are documented below for completeness.

OptixLogError

Signature

class OptixLogError(Exception): ...

The base class for every error raised by the OptixLog SDK. Catch this to handle all SDK errors in one place.

When raised — By any SDK call when an unexpected HTTP error (5xx after retries, or an unknown 4xx) or transport failure occurs. Also raised as a general fallback when a more specific subclass does not apply.

Which calls raise it — Any method that makes a network request can raise this.

How to handle

from optixlog import SDKClient, OptixLogError
from optixlog.pipeline import Pipeline
from optixlog_gen import SimulationNode

client = SDKClient(base_url="https://optixlog.leidos.com", api_key="sk-opt-...")
try:
    result = Pipeline(client).project("proj_grating_7f3a").ingest(
        data=SimulationNode(config={}, solver="fdtd"),
        prompt="Test run.",
    )
except OptixLogError as exc:
    print(f"SDK error: {exc}")

AuthenticationError

Signature

class AuthenticationError(OptixLogError): ...

When raised — The server returned HTTP 401 (Unauthorized) or 403 (Forbidden), meaning the API key was missing, malformed, expired, or lacks permission for the requested resource.

Which calls raise it — Any method that makes an authenticated network request. This includes all Management and Pipeline methods, as well as the CLI's login --validate flag.

How to handle — Check your API key and re-run optixlog login. If you are constructing SDKClient directly, verify api_key is correctly set and that the key has not been revoked.

from optixlog import SDKClient, AuthenticationError
from optixlog.management import Management

client = SDKClient(base_url="https://optixlog.leidos.com", api_key="sk-opt-invalid")
try:
    config = Management(client).project("proj_grating_7f3a").config.get()
except AuthenticationError:
    print("Invalid or missing API key. Run `optixlog login` to refresh credentials.")

NotFoundError

Signature

class NotFoundError(OptixLogError): ...

When raised — A strict .get(id) lookup found no resource with the given ID, or the server returned HTTP 404. Also raised by .one() when the filters match zero records.

Which calls raise it

• TeamCollection.get(team_id) — team not found.
• TeamMembershipCollection.get(user_id=...) — membership not found.
• WorkflowNodeCollection.get(node_id) — node not found.
• WorkflowNodeLabelCollection.get(label_id) — label not found.
• AuditEventCollection.get(audit_event_id) — event not found.
• ProjectConfigResource.get() — project config not found.
• ProjectOrganizationResource.get() — organization not found.
• Any .one() method when zero items match the filters.

How to handle — Use the _or_none variant (get_or_none, first) when you want to handle absence without an exception:

from optixlog import SDKClient, NotFoundError
from optixlog.management import Management

client = SDKClient(base_url="https://optixlog.leidos.com", api_key="sk-opt-...")
mgmt = Management(client).project("proj_grating_7f3a")

# Option 1: catch NotFoundError
try:
    node = mgmt.workflow_nodes.get("node_does_not_exist")
except NotFoundError:
    node = None

# Option 2: use get_or_none (no exception)
node = mgmt.workflow_nodes.get_or_none("node_does_not_exist")

MultipleResultsError

Signature

class MultipleResultsError(OptixLogError): ...

When raised — A .one() call matched more than one record. The SDK fetches up to 2 results with the given filters and raises this error when both slots are filled.

Which calls raise it

• TeamCollection.one(...) — more than one team matched.
• TeamMembershipCollection.one(...) — more than one membership matched.
• WorkflowNodeCollection.one(...) — more than one node matched.
• AuditEventCollection.one(...) — more than one audit event matched.

How to handle — Tighten your filter criteria, or switch to .list() / .iter() if you expect multiple results:

from optixlog import SDKClient, MultipleResultsError
from optixlog.management import Management

client = SDKClient(base_url="https://optixlog.leidos.com", api_key="sk-opt-...")
mgmt = Management(client).project("proj_grating_7f3a")

try:
    team = mgmt.teams.one(category="photonics")
except MultipleResultsError:
    # Multiple teams match — list them instead
    for t in mgmt.teams.iter(category="photonics"):
        print(t.id, t.name)

ValidationError

Signature

class ValidationError(OptixLogError): ...

When raised — The server rejected the request payload as invalid (HTTP 400 or 422). Common causes:

• Ingesting a node whose class name is not registered as a label in the project's schema.
• Passing fields that violate the project's node type schema.
• Missing required fields in an ingest payload.

Which calls raise it

• PipelineProject.ingest(...) — bad node_type or invalid field values.
• Any Management mutation (if applicable in future API versions).

How to handle — Check that the node class name matches a label in the project schema. Re-run optixlog generate to refresh bindings if the schema has changed:

from optixlog import SDKClient, ValidationError
from optixlog.pipeline import Pipeline
from optixlog_gen import SimulationNode

client = SDKClient(base_url="https://optixlog.leidos.com", api_key="sk-opt-...")
try:
    Pipeline(client).project("proj_grating_7f3a").ingest(
        data=SimulationNode(config={}, solver="fdtd"),
        prompt="Test.",
    )
except ValidationError as exc:
    print(f"Schema mismatch: {exc}")
    print("Try running `optixlog generate` to refresh bindings.")

CredentialsError

Signature

# from optixlog._credentials import CredentialsError
class CredentialsError(Exception): ...

When raised — No API key could be resolved from any source: neither an explicit api_key= argument, nor the OPTIXLOG_API_KEY environment variable, nor a stored profile in ~/.optixlog/credentials.toml.

Also raised if ~/.optixlog/credentials.toml exists but contains invalid TOML.

Which calls raise it

• OptixClient() construction (via resolve_credential()).
• Any direct call to resolve_credential().

How to handle — Run optixlog login to create a stored credential, or pass api_key= explicitly:

from optixlog._credentials import CredentialsError
from optixlog_gen import OptixClient

try:
    client = OptixClient()
except CredentialsError:
    print("Not logged in. Run `optixlog login` or set OPTIXLOG_API_KEY.")

ConfigError and ContractError

These errors are used internally by the CLI (optixlog init, optixlog generate) and the code-generation path. They are not raised by SDKClient, Management, or Pipeline.

• ConfigError — raised when optixlog.toml is missing, malformed, or lacks required fields.
• ContractError — raised when the codegen schema contract is violated (e.g. the server returned a schema that does not match the expected structure).

You will not encounter these in application code unless you are calling internal CLI helper functions directly.