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.

import {
  AlterSDKError,
  BackendError,
  GrantNotFoundError,
  GrantExpiredError,
  GrantRevokedError,
  AmbiguousGrantError,
  NoDelegatedGrantError,
  PolicyViolationError,
  ScopeReauthRequiredError,
  NetworkError,
  TimeoutError,
  ConnectFlowError,
  ApprovalDeniedError,
  LastActiveKeyError,
} from "@alter-ai/alter-sdk";

​
Hierarchy

Identical to the Python SDK, with TypeScript class names: 
AlterSDKError
├── AlterValueError
├── BackendError
│   ├── ReAuthRequiredError
│   │   ├── GrantExpiredError
│   │   ├── GrantRevokedError
│   │   ├── CredentialRevokedError
│   │   └── GrantDeletedError
│   ├── GrantNotFoundError
│   ├── AmbiguousGrantError
│   ├── NoDelegatedGrantError
│   ├── PolicyViolationError
│   └── AgentError
│       ├── InvalidKeyError
│       ├── AgentNotFoundError
│       ├── AgentNameExistsError
│       ├── AgentInactiveError
│       ├── AgentRevokedError
│       ├── KeyRevokedError
│       ├── KeyAlreadyRevokedError
│       ├── KeyNotFoundError
│       ├── LastActiveKeyError
│       ├── MeRequiresAgentKeyError
│       ├── AgentCannotMintSubagentsError
│       ├── AgentScopeNarrowingNotSupportedError
│       ├── IdempotencyKeyBodyMismatchError
│       ├── IdempotencyKeyAgentRevokedError
│       └── IdempotencyKeyAgentInactiveError
├── ConnectFlowError
│   ├── ConnectDeniedError
│   ├── ConnectConfigError
│   └── ConnectTimeoutError
├── ProviderAPIError
│   └── ScopeReauthRequiredError
├── ApprovalError
│   ├── ApprovalDeniedError
│   ├── ApprovalExpiredError
│   ├── ApprovalTimeoutError
│   └── ApprovalExecutionFailedError
└── NetworkError
    └── TimeoutError

​
What to catch

ErrorLikely causeAction
AlterValueErrorBad argumentsFix the call. Don’t retry.
GrantNotFoundErrorGrant deleted, wrong ID, or JWT identity resolves to no grantRe-run OAuth. Don’t retry.
GrantExpiredErrorRefresh token expiredRe-run OAuth.
GrantRevokedErrorRevoked by user or operatorRe-run OAuth.
AmbiguousGrantErrorJWT identity, multiple grantsPass account to disambiguate. Carries appUserIds.
NoDelegatedGrantErrorAgent has no delegation for this userRe-run Connect with the agent set.
PolicyViolationErrorPolicy deniedInspect reason.
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.retryInfo: RetryInfo | null: 
const response = await vault.request("GET", url, { grantId: g });
if (response.retryInfo && response.retryInfo.totalAttempts > 1) {
  console.log(`Recovered after ${response.retryInfo.totalAttempts} attempts`);
}
The matching Python field is response.retry_info.total_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