> For the complete documentation index, see [llms.txt](https://docs.augustdigital.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.augustdigital.io/developers/typescript-sdk/errors.md). # Error Handling All public SDK methods throw typed errors that extend a common base class, `AugustSDKError`. Catch by class for broad handling, or narrow on the `code` field for actionable, per-failure logic. ## Hierarchy ``` AugustSDKError // base — every SDK error extends this ├── AugustAuthError // missing / invalid / forbidden key ├── AugustValidationError // caller-side input failed validation ├── AugustNetworkError // network or transport-level failure ├── AugustTimeoutError // request exceeded its deadline ├── AugustRateLimitError // backend returned 429 (or equivalent) └── AugustServerError // backend returned a non-OK status ``` Every instance carries: | Property | Type | Description | | --------------- | -------------------------- | -------------------------------------------------------------------------- | | `code` | `AugustErrorCode` | Stable string identifier — narrow on this for per-case handling. | | `message` | `string` | Human-readable description suitable for surfacing in dev tools. | | `correlationId` | `string \| undefined` | Set from the response `x-correlation-id` header when the SDK received one. | | `context` | `Record?` | Structured payload (e.g. `{ target, amount }`) attached for logging. | | `cause` | `unknown` | Original error from the underlying RPC / fetch — preserved for inspection. | | `stack` | `string` | Native stack trace. | `AugustTimeoutError` adds `timeoutMs` (the deadline that elapsed). `AugustRateLimitError` adds an optional `retryAfterMs`. `AugustServerError` adds `status` (the HTTP status code). All instances expose `toJSON()` so `JSON.stringify(err)` returns a useful object — native `Error` serializes to `"{}"` without this. ## Codes | Class | Code | When it fires | Recommended action | | ----------------------- | -------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | `AugustAuthError` | `AUTH_MISSING_KEY` | Required August API key was not supplied to the SDK constructor. | Pass `keys.august` into `new AugustSDK({...})`. | | `AugustAuthError` | `AUTH_INVALID_KEY` | Backend rejected the supplied key (malformed or revoked). | Verify the key value; rotate if needed. | | `AugustAuthError` | `AUTH_FORBIDDEN` | Backend returned HTTP 403 — key lacks permission for this endpoint. | Check the key's permitted scopes; do not retry. | | `AugustAuthError` | `AUTH_UNAUTHORIZED` | Backend returned HTTP 401 — key was not accepted. | Re-verify the key; do not retry without rotating. | | `AugustValidationError` | `INVALID_INPUT` | Required field missing, `NaN` / `Infinity` amount, or JS number above `Number.MAX_SAFE_INTEGER`. | Fix the input before retrying. | | `AugustValidationError` | `INVALID_ADDRESS` | Address fails checksum / wrong length, or is not valid for the target chain family (EVM / Solana). | Fix the input. | | `AugustValidationError` | `INVALID_CHAIN` | Chain ID is not in the SDK's allowlist for this operation. | Pass a supported chain. | | `AugustValidationError` | `INVALID_URL` | A user-supplied URL failed validation. | Fix the URL. | | `AugustValidationError` | `ACCOUNT_NOT_FUNDED` | Stellar (Soroban) deposit/redeem source account has never been activated on-chain (zero balance). | Send ≥1 XLM to the address to activate it, then retry. | | `AugustNetworkError` | `NETWORK_ERROR` | Underlying `fetch` / WebSocket failed (DNS, connection refused, offline). | Safe to retry with backoff. | | `AugustTimeoutError` | `TIMEOUT` | Request exceeded its deadline (default 90 s, configurable per-call). | Backoff + retry; check chain / RPC status. | | `AugustRateLimitError` | `RATE_LIMITED` | Backend returned HTTP 429 (or equivalent rate-limit signal). | Wait `retryAfterMs` before retrying. | | `AugustServerError` | `SERVER_ERROR` | Backend returned a non-OK status that is not auth / rate-limit / timeout. | Inspect `.status` and `.context`; retry conservatively. | | `AugustSDKError` (base) | `UNKNOWN` | Wrapped failure from an RPC / contract call. Original error preserved on `.cause`. | Inspect `.cause` and `.context`; do not retry blindly. | ## Narrowing patterns ### Catch broadly, narrow by code Best for transactional flows where you want one block of recovery logic per failure category. ```typescript import { AugustAuthError, AugustValidationError, AugustTimeoutError, AugustRateLimitError, AugustSDKError, } from '@augustdigital/sdk'; try { await augustSdk.evm.vaultDeposit({ target: vaultAddress, wallet: userAddress, amount: '100', }); } catch (err) { if (err instanceof AugustValidationError) { if (err.code === 'INVALID_INPUT') return showFormError(err.message); if (err.code === 'INVALID_ADDRESS') return showAddressError(); if (err.code === 'ACCOUNT_NOT_FUNDED') { // Stellar only: the source account needs ≥1 XLM to be activated on-chain. // err.message includes the address and the funding hint. return showFundingPrompt(err.message); } } if (err instanceof AugustAuthError) { return showAuthError('Check your August API key.'); } if (err instanceof AugustTimeoutError) { // err.timeoutMs is the deadline that elapsed return scheduleRetry(err.timeoutMs); } if (err instanceof AugustRateLimitError) { return scheduleRetry(err.retryAfterMs ?? 5_000); } if (err instanceof AugustSDKError) { // Wrapped downstream failure — inspect cause for the underlying revert / RPC error reportError(err.code, err.context, err.cause); return; } throw err; } ``` ### Catch using the type guard Use `isAugustSDKError` when you receive an `unknown` value (e.g. in a global error handler) and want to keep the rest of the runtime's errors flowing through untouched. ```typescript import { isAugustSDKError } from '@augustdigital/sdk'; window.addEventListener('unhandledrejection', (event) => { if (isAugustSDKError(event.reason)) { reportSdkError(event.reason); event.preventDefault(); } }); ``` The guard works across realms (Web Worker, VM contexts) where `instanceof` fails. ### Inspect the original cause Wrapped errors keep the underlying failure on `.cause`: ```typescript try { await augustSdk.evm.vaultRequestRedeem({ target, wallet, amount }); } catch (err) { if (err instanceof AugustSDKError && err.code === 'UNKNOWN') { console.error('Underlying error:', err.cause); console.error('Context:', err.context); } throw err; } ``` For on-chain reverts, `.cause` is the original `ethers` / `viem` error, so revert reasons and gas info remain accessible. ## Retry guidance | Class | Safe to retry? | Notes | | -------------------------- | ------------------------- | ------------------------------------------------------------------- | | `AugustValidationError` | No | The input is wrong; retrying will fail the same way. | | `AugustAuthError` | No | Fix the key first. | | `AugustNetworkError` | Yes, with backoff | Transient by definition. | | `AugustTimeoutError` | Yes, with backoff | Consider raising `timeoutMs` if the operation is legitimately slow. | | `AugustRateLimitError` | Yes, after `retryAfterMs` | Honor the suggested wait. | | `AugustServerError` | Conditionally | Retry on 5xx with backoff; treat 4xx as terminal. | | `AugustSDKError` `UNKNOWN` | Conditionally | Inspect `.cause` first — an on-chain revert is not retryable. | ## Serialization for logging Every SDK error implements `toJSON()`, so logging with `JSON.stringify` preserves the structured fields: ```typescript try { await augustSdk.getVault({ vault }); } catch (err) { if (err instanceof AugustSDKError) { logger.error('sdk_error', JSON.stringify(err)); } throw err; } ``` The serialized payload includes `name`, `message`, `code`, `correlationId`, `context`, `stack`, and a compact `cause` summary. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.augustdigital.io/developers/typescript-sdk/errors.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.