correspond.errors#

What correspond raises, and the vocabulary a failed write reports.

Two families, on purpose:

Mistakes a caller fixes in code or configuration raise: an unknown channel (UnknownChannel), a malformed conversation reference (InvalidRef), an operation the channel does not have (NotSupported). A retry changes nothing.
Failures of the platform or of the message are ChannelError inside an adapter, carrying an kind from ERROR_KINDS, retryable and retry_after. Reads let them propagate; the write verbs turn them into a SendResult with ok=False, so a notifier never crashes its caller.

A third family stops a write before it leaves: the before_send check (see correspond.outbound) raises Refused or NeedsApproval, and the write verbs report it as a SendResult whose error_kind is one of CHECK_KINDS.

>>> str(NotSupported("react", "ntfy"))
'ntfy does not support react'
>>> error = ChannelError("slow down", kind="rate_limited", retryable=True, retry_after=30)
>>> error.kind, error.retryable, error.retry_after
('rate_limited', True, 30.0)
>>> held = NeedsApproval("public audience")
>>> held.error_kind, held.reason
('needs_approval', 'public audience')

Module Attributes

`ERROR_KINDS`	Why a platform call failed, for a caller deciding whether to retry, fix the draft, or ask a human.
`CHECK_KINDS`	Why the `before_send` check stopped a write.

Exceptions

`BeforeSendFailed`(reason, **details)	The `before_send` check raised something else, or returned a value, so nothing is sent.
`BeforeSendUnavailable`(reason, **details)	The configured `before_send` check could not be loaded, so nothing is sent.
`ChannelError`(message, *, kind[, retryable, ...])	A platform call that failed, classified so the caller can decide what to do.
`CorrespondError`	An expected failure, with a message meant for the person or agent that asked.
`InvalidRef`	A conversation reference that does not parse, or that its channel rejects.
`MissingRequirement`(channel, missing, *, fix)	Something the channel needs is not here: a credential, a binary, an extra, an OS.
`NeedsApproval`(reason, **details)	Draft to operator: the write waits for the operator's approval.
`NotSupported`(operation, channel, *[, ...])	The channel does not have this operation (or this feature of it).
`Refused`(reason, **details)	Block: this draft does not go to this conversation as written.
`Stopped`(reason, **details)	A write the `before_send` check did not let leave: `error_kind` says how, `reason` says why.
`UnknownChannel`(channel, *[, known, hint])	A channel name that no registered adapter answers to.

exception correspond.errors.BeforeSendFailed(reason, **details)[source]#

Bases: Stopped

The before_send check raised something else, or returned a value, so nothing is sent.

exception correspond.errors.BeforeSendUnavailable(reason, **details)[source]#

Bases: Stopped

The configured before_send check could not be loaded, so nothing is sent.

correspond.errors.CHECK_KINDS = ('refused', 'needs_approval', 'before_send_unavailable', 'before_send_failed')#: Why the before_send check stopped a write. Nothing was sent; a retry of the same draft changes nothing.

exception correspond.errors.ChannelError(message, *, kind, retryable=False, retry_after=None)[source]#

Bases: CorrespondError

A platform call that failed, classified so the caller can decide what to do.

exception correspond.errors.CorrespondError[source]#

Bases: Exception

An expected failure, with a message meant for the person or agent that asked.

correspond.errors.ERROR_KINDS = ('auth', 'permission', 'not_found', 'rate_limited', 'network', 'validation', 'unavailable', 'unconfirmed')#: Why a platform call failed, for a caller deciding whether to retry, fix the draft, or ask a human.

exception correspond.errors.InvalidRef[source]#

Bases: CorrespondError, ValueError

A conversation reference that does not parse, or that its channel rejects.

exception correspond.errors.MissingRequirement(channel, missing, *, fix, kind='unavailable')[source]#

Bases: ChannelError

Something the channel needs is not here: a credential, a binary, an extra, an OS.

exception correspond.errors.NeedsApproval(reason, **details)[source]#

Bases: Stopped

Draft to operator: the write waits for the operator’s approval. Raised by a before_send check.

exception correspond.errors.NotSupported(operation, channel, *, alternatives=())[source]#

Bases: CorrespondError

The channel does not have this operation (or this feature of it). Never a silent no-op.

exception correspond.errors.Refused(reason, **details)[source]#

Bases: Stopped

Block: this draft does not go to this conversation as written. Raised by a before_send check.

exception correspond.errors.Stopped(reason, **details)[source]#

Bases: CorrespondError

A write the before_send check did not let leave: error_kind says how, reason says why.

Keyword details (an approval id, a draft hash) travel with the result, in the plan’s before_send_details.

exception correspond.errors.UnknownChannel(channel, *, known=(), hint='')[source]#

Bases: CorrespondError, LookupError

A channel name that no registered adapter answers to.