Exceptions

Everything the SDK raises on purpose is a KorchError subclass with a stable code — no raw temporalio/httpx/dspy exception ever crosses a public boundary.

KorchError

KorchError(
    message: str, *, code: str | None = None, **context: str
)

Bases: Exception

Base class for every error the SDK raises.

Catching KorchError catches everything the SDK can raise deliberately. Each instance carries a stable code (from :mod:korchestrator.constants.error_codes, part of the compatibility surface) and an optional context mapping of tenant-safe string fields.

Parameters:

Name	Type	Description	Default
message	str	A human-readable, actionable message — what failed, which value was involved, and what to do. It MUST NOT contain secrets or a full prompt.	required
code	str | None	The stable error code. Defaults to the class's default_code.	None
**context	str	Tenant-safe string fields describing the failure (e.g. model="gpt-4o").	{}

Example

from korchestrator.exceptions import KorchError, ValidationError err = ValidationError("Objective must be at least 10 characters.") err.code 'KORCH_VALIDATION_FAILED' isinstance(err, KorchError) True

Build the error with an actionable message, a stable code, and string context.

AuthError

AuthError(
    message: str, *, code: str | None = None, **context: str
)

Bases: KorchError

Authentication failed or the caller is not authorized for the resource/tenant.

ValidationError

ValidationError(
    message: str, *, code: str | None = None, **context: str
)

Bases: KorchError

Input failed validation at a trust boundary, before any effect took place.

NetworkError

NetworkError(
    message: str, *, code: str | None = None, **context: str
)

Bases: KorchError

A network dependency was unavailable or unreachable.

ProviderError

ProviderError(
    message: str, *, code: str | None = None, **context: str
)

Bases: KorchError

An upstream model or service provider failed.

TimeoutError

TimeoutError(
    message: str, *, code: str | None = None, **context: str
)

Bases: KorchError

An operation exceeded its deadline.

Deliberately shadows the builtin TimeoutError inside the package namespace; it subclasses KorchError only. Import it explicitly (from korchestrator.exceptions import TimeoutError) so the shadowing is visible at the import site.

RateLimitError

RateLimitError(
    message: str, *, code: str | None = None, **context: str
)

Bases: KorchError

A provider or gateway rate limit was hit.

QuotaExceededError

QuotaExceededError(
    message: str, *, code: str | None = None, **context: str
)

Bases: KorchError

A tenant or account quota was exhausted.

RoutingError

RoutingError(
    message: str, *, code: str | None = None, **context: str
)

Bases: KorchError

No model could be selected for a task, or routing otherwise failed.

GovernanceHaltError

GovernanceHaltError(
    message: str, *, code: str | None = None, **context: str
)

Bases: KorchError

Governance halted the run because trust fell below the configured threshold.

RunFailedError

RunFailedError(
    message: str, *, code: str | None = None, **context: str
)

Bases: KorchError

A run terminated in a failed state.

RunTimeoutError

RunTimeoutError(
    message: str, *, code: str | None = None, **context: str
)

Bases: KorchError

A run exceeded its max_supersteps or wall-clock bound.

ToolError

ToolError(
    message: str, *, code: str | None = None, **context: str
)

Bases: KorchError

A tool invocation failed, was not found, or was denied.

The specific case is carried by code — TOOL_NOT_FOUND, TOOL_ACCESS_DENIED, or NOT_IMPLEMENTED — which callers pass explicitly.

MissingExtraError

MissingExtraError(
    message: str, *, code: str | None = None, **context: str
)

Bases: KorchError

An optional extra is required but not installed.

Raised at a lazy-import site instead of a bare ImportError; the message names the extra and the exact pip install command.

Example

from korchestrator.exceptions import KorchError, MissingExtraError try: ... raise MissingExtraError( ... "The cognitive layer requires the 'dspy' extra. " ... "Install it with: pip install 'korchestrator[dspy]'" ... ) ... except KorchError as exc: ... print(exc.code) KORCH_MISSING_EXTRA

ConfigurationError

ConfigurationError(
    message: str, *, code: str | None = None, **context: str
)

Bases: KorchError

Configuration is invalid: a bad value, range, enum, or mutually exclusive setting.