Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.alterauth.com/llms.txt

Use this file to discover all available pages before exploring further.

from alter_sdk import (
    AlterSDKError,
    BackendError,
    GrantNotFoundError,
    GrantExpiredError,
    GrantRevokedError,
    AmbiguousGrantError,
    NoDelegatedGrantError,
    PolicyViolationError,
    ScopeReauthRequiredError,
    NetworkError,
    TimeoutError,
    ConnectFlowError,
    ApprovalDeniedError,
    LastActiveKeyError,
)

​
Hierarchy

AlterSDKError
├── AlterValueError                    # bad arguments before backend call
├── BackendError                       # backend rejected the call
│   ├── ReAuthRequiredError            # the grant is no longer usable
│   │   ├── GrantExpiredError
│   │   ├── GrantRevokedError
│   │   ├── CredentialRevokedError
│   │   └── GrantDeletedError
│   ├── GrantNotFoundError
│   ├── AmbiguousGrantError            # JWT identity, multiple matching grants
│   ├── NoDelegatedGrantError          # agent has no delegation for the user
│   ├── PolicyViolationError
│   └── AgentError                     # base for agent / key errors
│       ├── InvalidKeyError
│       ├── AgentNotFoundError
│       ├── AgentNameExistsError
│       ├── AgentInactiveError
│       ├── AgentRevokedError
│       ├── KeyRevokedError
│       ├── KeyAlreadyRevokedError
│       ├── KeyNotFoundError
│       ├── LastActiveKeyError
│       ├── MeRequiresAgentKeyError
│       ├── AgentCannotMintSubagentsError
│       ├── AgentScopeNarrowingNotSupportedError
│       ├── IdempotencyKeyBodyMismatchError
│       ├── IdempotencyKeyAgentRevokedError
│       └── IdempotencyKeyAgentInactiveError
├── ConnectFlowError                   # vault.connect() failures
│   ├── ConnectDeniedError
│   ├── ConnectConfigError
│   └── ConnectTimeoutError
├── ProviderAPIError                   # upstream provider returned non-2xx
│   └── ScopeReauthRequiredError       # provider says scopes are insufficient
├── ApprovalError
│   ├── ApprovalDeniedError
│   ├── ApprovalExpiredError
│   ├── ApprovalTimeoutError
│   └── ApprovalExecutionFailedError
└── NetworkError
    └── TimeoutError

​
What to catch

ExceptionLikely causeAction
AlterValueErrorBad argumentsFix the call. Don’t retry.
GrantNotFoundErrorGrant deleted, wrong ID, or JWT identity resolves to a user with no grantRe-run OAuth. Don’t retry.
GrantExpiredErrorRefresh token expiredRe-run OAuth. Don’t retry.
GrantRevokedErrorRevoked by user or operatorRe-run OAuth. Don’t retry.
AmbiguousGrantErrorJWT identity, user has multiple grantsPass account= to disambiguate. Carries app_user_ids.
NoDelegatedGrantErrorAgent has no delegation for this userRe-run Connect with agent= set.
PolicyViolationErrorPolicy denied the callInspect policy reason. Don’t retry.
ScopeReauthRequiredErrorProvider rejected for missing scopeRe-run OAuth with broader scopes.
NetworkError, TimeoutErrorTransientRetry with backoff.
BackendError (other 5xx)TransientRetry with backoff.

​
Retry guidance

The SDK retries network/timeout errors automatically up to 3 times with exponential backoff. Per-call retry metadata is on response.retry_info: RetryInfo | None: 
response = await vault.request("GET", url, grant_id=g)
if response.retry_info and response.retry_info.total_attempts > 1:
    print(f"Recovered after {response.retry_info.total_attempts} attempts")
Avoid wrapping request() in an additional retry loop for transient errors — the SDK already retries. Retry application-level transient logic (DB calls, queue publishes) around BackendError.

​
See also