Exceptions#

Import these types from sfdctrust. All SDK failures share TrustCenterError. A timeout is also a network failure; authentication, rate-limit and not-found errors are also API status failures. Malformed successful responses have their own branch.

TrustCenterError
├── ConfigurationError
├── NetworkError
│   └── RequestTimeoutError
├── APIStatusError
│   ├── AuthenticationError   (401)
│   ├── RateLimitError        (429)
│   └── NotFoundError         (404)
├── MalformedResponseError
├── PaginationError
├── PATRefreshPendingError
├── PATRefreshAmbiguousError
└── PATPersistenceError

APIStatusError(status_code) accepts integer statuses from 400 through 599. Its specialized subclasses take no arguments and set their fixed status. These errors retain only status_code and a static message containing that status. They do not accept server messages, raw requests, responses or headers. Request-ID capture is deferred until a documented safe source is verified.

The other branches accept ordinary exception arguments for SDK-authored, secret-free messages. Never pass server content, credential values, HTTPX requests or raw exception text to them. The existing base exception’s construction behavior is preserved.

A 401 does not distinguish invalid, missing, revoked or expired credentials. A 404 does not distinguish nonexistent from unauthorized resources. A 429 does not imply a JSON body or a Retry-After header. The exceptions perform no I/O, retries or credential refresh. The private transport translates HTTP statuses before reading the response body and uses the base TrustCenterError for unexpected statuses such as redirects.

A traversal raises PaginationError if a further page would reuse a cursor or exceed max_pages. A lazy iterator may have already yielded items. A server rejection of a cursor with HTTP 400 raises APIStatusError.

Async task cancellation propagates as asyncio.CancelledError. See Authentication and PAT rotation for the durable state left by interrupted rotation.

class sfdctrust.TrustCenterError[source]#

Base class for sfdctrust exceptions.

class sfdctrust.ConfigurationError[source]#

Invalid SDK configuration; messages must be SDK-authored and secret-free.

class sfdctrust.NetworkError[source]#

A request could not complete because of a network failure.

Construct with a safe SDK-authored message, never an underlying exception’s text, request, URL, headers, or response body.

class sfdctrust.RequestTimeoutError[source]#

A request exceeded its configured timeout.

class sfdctrust.APIStatusError(status_code)[source]#

An API request returned an unsuccessful HTTP status.

Only the status is retained. Raw requests, responses, and server messages are deliberately excluded. Request IDs are deferred until a documented, safe source is verified; no header name is assumed.

Parameters:

status_code (int) – An HTTP error status from 400 through 599.

Raises:

ValueError – If the status is not an integer HTTP error status.

class sfdctrust.AuthenticationError[source]#

HTTP 401: the PAT is missing, invalid, revoked, or expired.

This error does not identify which condition occurred and never triggers PAT refresh or credential replacement.

class sfdctrust.RateLimitError[source]#

HTTP 429, without assuming JSON content or retry-related headers.

class sfdctrust.NotFoundError[source]#

HTTP 404: the resource does not exist or is not authorized.

class sfdctrust.MalformedResponseError[source]#

A successful response could not be decoded or validated.

Construct with a safe SDK-authored message, without response content or validation errors that might echo sensitive input.

class sfdctrust.PaginationError[source]#

A traversal requires another page but reached its limit or repeated a cursor.

See Authentication and PAT rotation for refresh outcomes and the recovery procedure.

class sfdctrust.PATRefreshPendingError[source]#

A pending or competing rotation prevents the requested operation.

class sfdctrust.PATProbeResult(*values)[source]#

Result of the single read-only check with the old PAT.

class sfdctrust.PATRefreshAmbiguousError(probe)[source]#

Salesforce may have rotated the PAT without returning a usable replacement.

Parameters:

probe (PATProbeResult) – Sanitized result of the old PAT check.

class sfdctrust.PATPersistenceError[source]#

A required durable PAT store transition could not be confirmed.