Error Codes

Pollar surfaces errors in two places: the Server / SDK API (HTTP responses) and the client SDK (method outcomes, thrown errors and reactive state). This page documents both, plus the error codes, for @pollar/core 0.12 and API v3. For 0.11.x, see the 0.11 reference.

Error model

Server / SDK API responses

Every API response uses a fixed envelope. Errors are flat: there is no error wrapper and no status field in the body (the HTTP status code carries the status):

{
  "code": "INSUFFICIENT_FUNDS_FOR_TRUSTLINE",
  "success": false
}

Some errors include extra fields: validation issues in details, a human-readable message (a ramp payee the provider would refuse, an API version that is retired), or the data the error is about (rejected on a ramp quote with no route, reasons on a blocked custody migration):

{
  "code": "VALIDATION_ERROR",
  "success": false,
  "details": { "fieldErrors": { "publicKey": ["Must start with G"] } }
}

Successful responses are { "content": <data>, "code": "<SUCCESS_CODE>", "success": true }.

Client SDK

The transaction methods of @pollar/core do not throw on operational failures. Instead they:

• Return an outcome object: buildTx, signAndSubmitTx, runTx, sendPayment resolve to { status: 'error', code?, details?, resultCode?, message? } (vs 'built' | 'success' | 'pending' | 'cosign_pending').
• Drive reactive state: tx.step === 'error' carries { phase, details }; auth/balance/history states expose { step: 'error', message }.

const result = await pollar.runTx('payment', { destination, amount, asset });
if (result.status === 'error') {
  console.error(result.code, result.details, result.resultCode);
}

Other methods (wallet creation, KYC, requirements, cards, ramps, co-sign and recovery) throw when the API refuses. Three kinds of error are thrown; check them by code or with the exported guards:

import { isPollarApiError, isPollarNetworkError } from '@pollar/core';

try {
  await pollar.createWallet();
} catch (err) {
  if (isPollarApiError(err) && err.code === 'SDK_WALLET_PROVISIONING_DISABLED') {
    // the app creates no wallets
  } else if (isPollarNetworkError(err)) {
    // retry later
  }
}

Auth flow error codes (surfaced on the error AuthState) are exported as AUTH_ERROR_CODES (e.g. SESSION_EXPIRED, EMAIL_CODE_INVALID, WALLET_AUTH_FAILED, PASSKEY_FAILED).

Text to show the user

@pollar/core exports the messages its own UI shows, so a custom UI phrases errors the same way:

• transactionErrorMessage(code, details?): the text for a transaction failure, from the code or the on-chain result code.
• appUnavailableMessage(err): the text for SDK_CREDITS_INSUFFICIENT / SDK_BILLING_OVERDUE, an error the user cannot fix and the app must; null for any other error.
• cosignRefusalMessage(err): the text for SDK_COSIGN_TURNKEY_REJECTED, with the wallet provider's own reason when it gave one; null for any other error.

Auth, API keys & access

Keys are network-specific by prefix: pub_testnet_ / pub_mainnet_ (publishable) and sec_testnet_ / sec_mainnet_ (secret).

Credits

Apps on credits pay Pollar per use (see Credits). A paid call is refused before anything moves when the app cannot pay:

Validation & general

Wallet & funding

Co-signed and self-custody wallets (Turnkey)

Apps whose wallets live in Turnkey (see Co-signed Wallets). A signing call that needs the user's vote is not an error: it answers 202 SDK_COSIGN_PENDING and the SDK reports status: 'cosign_pending'.

Signature confirmation

SDK only. Every signing call passes the app's confirmation policy first (see Signature confirmation).

Trustlines

Signer rotation

Transactions

When the network refuses a transaction for a known reason, the code names it (all 422):

transactionErrorMessage(code, details) returns the text the SDK's own modals show for each.

Soroban auth entries

Returned by POST /tx/sign-auth-entry (pollar.signAuthEntry()) when the app's allowlist refuses to authorize an entry, and by the dashboard/Server API when a row is saved. Configured under Wallets > Auth Policy.

Every denial here also carries applicationId and applicationName: the app the decision was made against, which is the app your API key resolves to, not necessarily the one open in the dashboard.

{
  "code": "SOROBAN_AUTH_NO_POLICY",
  "success": false,
  "message": "no Soroban auth-entry allowlist is configured for this application",
  "applicationId": "cm...",
  "applicationName": "Acme Checkout"
}

Saving an allowlist row (dashboard or Server API) can also answer:

Swaps

Distribution

KYC

Ramps

Ramps run on /v3/ramps (see Ramps).

Cards

Session, DPoP & passkeys

End-user session and token errors (sdk-api). These are handled by the SDK's auth flow; surface to users as "please sign in again".

This is not the full enum: the server defines additional internal codes (hub-api admin, Pollar Pay, wallet services). The codes above are the ones an SDK or Server API integrator is most likely to encounter.

Handling errors in the SDK

import { appUnavailableMessage, isPollarApiError, transactionErrorMessage } from '@pollar/core';

// Transaction failures come back as outcomes: no try/catch needed.
const result = await pollar.runTx('payment', { destination, amount, asset });
if (result.status === 'error') {
  if (result.code === 'SDK_CONFIRMATION_DECLINED') return; // the user said no
  showError(appUnavailableMessage(result) ?? transactionErrorMessage(result.code, result.details));
}

// Methods that call the API directly throw.
try {
  const quotes = await pollar.quoteRamp(request);
} catch (err) {
  if (isPollarApiError(err) && err.code === 'SDK_RAMPS_NO_ROUTE') {
    // err.body.rejected lists every route and why it was dropped
  }
}

// Calling a flow step out of order throws an error with code 'INVALID_FLOW'.
try {
  pollar.verifyEmailCode('123456');
} catch (err) {
  if ((err as { code?: string }).code === 'INVALID_FLOW') {
    // wrong step for the current AuthState
  }
}

To observe transaction failures reactively, subscribe to onTransactionStateChange and inspect state.phase / state.details when state.step === 'error'.