Exceptions and Redaction

Package exceptions expose stable code values for application-level handling. Redaction helpers reduce accidental disclosure in logs and diagnostics, but they do not replace careful data classification and access controls.

errors

Typed Survey Scribe errors and safe redaction helpers.

SurveyScribeError

Bases: Exception

Base class for stable public Survey Scribe errors.

code class-attribute instance-attribute

code = 'SURVEY_SCRIBE_ERROR'

ProgrammerInputError

Bases: SurveyScribeError, TypeError

A caller supplied an invalid API object or argument shape.

code class-attribute instance-attribute

code = 'PROGRAMMER_INPUT_INVALID'

RunningEventLoopError

Bases: SurveyScribeError, RuntimeError

A synchronous facade was called from a running event loop.

code class-attribute instance-attribute

code = 'RUNNING_EVENT_LOOP'

ClientClosedError

Bases: SurveyScribeError, RuntimeError

A conversion was requested after its facade was closed.

code class-attribute instance-attribute

code = 'CLIENT_CLOSED'

ConversionFailedError

Bases: SurveyScribeError, RuntimeError

A compatibility entry point cannot return a failed result envelope.

code class-attribute instance-attribute

code = 'CONVERSION_FAILED'

ConfigurationError

Bases: SurveyScribeError, ValueError

Configuration cannot be loaded or validated.

code class-attribute instance-attribute

code = 'CONFIGURATION_INVALID'

AmbiguousCredentialError

Bases: ConfigurationError

More than one mutually exclusive credential form was supplied.

code class-attribute instance-attribute

code = 'CREDENTIALS_AMBIGUOUS'

ArtifactError

Bases: SurveyScribeError

Base class for artifact transaction errors.

code class-attribute instance-attribute

code = 'ARTIFACT_ERROR'

ArtifactCollisionError

Bases: ArtifactError, FileExistsError

An artifact exists or another writer owns the survey lock.

code class-attribute instance-attribute

code = 'ARTIFACT_COLLISION'

ArtifactWriteError

ArtifactWriteError(stage: str, message: str)

Bases: ArtifactError, OSError

A required artifact transaction stage failed.

code class-attribute instance-attribute

code = 'ARTIFACT_WRITE_FAILED'

stage instance-attribute

stage = stage

redact_text

redact_text(
    value: str, *, sensitive_values: Sequence[str] = ()
) -> str

Redact recognized credentials and explicit sensitive values best-effort.

Arbitrary secret formats cannot be detected. Callers must provide known values through sensitive_values and avoid recording raw request objects.

is_sensitive_key

is_sensitive_key(value: str) -> bool

Return whether a field name denotes recognized sensitive content.

is_sensitive_query_key

is_sensitive_query_key(value: str) -> bool

Return whether an exact URL query key carries credentials.

redact_exception

redact_exception(
    error: BaseException,
    *,
    sensitive_values: Sequence[str] = (),
) -> str

Render an exception chain without retaining nested sensitive values.

redact_data

redact_data(
    value: Any, *, sensitive_values: Sequence[str] = ()
) -> Any

Recursively redact mappings, sequences, strings, and exceptions.

Provider exceptions

base

Provider-neutral structured generation port and safe normalized results.

ProviderError

ProviderError()

Bases: Exception

Base provider error with one fixed safe message and code.

code class-attribute instance-attribute

code = 'PROVIDER_ERROR'

safe_message class-attribute instance-attribute

safe_message = 'Structured provider operation failed.'

ProviderDependencyError

ProviderDependencyError(
    extra: Literal["openai", "anthropic"] = "openai",
)

Bases: ProviderError, ImportError

The selected optional provider extra is unavailable.

code class-attribute instance-attribute

code = 'PROVIDER_DEPENDENCY_MISSING'

safe_message class-attribute instance-attribute

safe_message = f"The optional '{extra}' extra is required for this provider."

ProviderCapabilityError

ProviderCapabilityError(
    reason: Literal[
        "strict",
        "schema",
        "setting",
        "output_limit",
        "input_limit",
        "drift",
    ] = "strict",
)

Bases: ProviderError, ValueError

A requested model, schema, limit, or setting is unsupported.

code class-attribute instance-attribute

code = 'PROVIDER_CAPABILITY_UNSUPPORTED'

safe_message class-attribute instance-attribute

safe_message = messages[reason]

ProviderTransportError

ProviderTransportError(*, retryable: bool)

Bases: ProviderError

A provider transport failed with normalized retryability.

code class-attribute instance-attribute

code = 'PROVIDER_TRANSPORT_FAILED'

safe_message class-attribute instance-attribute

safe_message = 'The structured provider transport failed.'

retryable instance-attribute

retryable = retryable

ProviderAuthenticationError

ProviderAuthenticationError()

Bases: ProviderTransportError

Provider credentials were rejected.

code class-attribute instance-attribute

code = 'PROVIDER_AUTHENTICATION_FAILED'

safe_message class-attribute instance-attribute

safe_message = 'Provider authentication failed.'

ProviderRateLimitError

ProviderRateLimitError()

Bases: ProviderTransportError

The provider applied a retryable rate limit.

code class-attribute instance-attribute

code = 'PROVIDER_RATE_LIMITED'

safe_message class-attribute instance-attribute

safe_message = (
    "The structured provider rate limit was exhausted."
)

ProviderValidationError

ProviderValidationError()

Bases: ProviderError, ValueError

All bounded structured-response validation attempts failed.

code class-attribute instance-attribute

code = 'PROVIDER_VALIDATION_FAILED'

safe_message class-attribute instance-attribute

safe_message = 'The structured response validation failed.'

ProviderTruncationError

ProviderTruncationError()

Bases: ProviderError

The provider reported an incomplete length-limited response.

code class-attribute instance-attribute

code = 'PROVIDER_RESPONSE_TRUNCATED'

safe_message class-attribute instance-attribute

safe_message = 'The structured response was truncated.'