Error Codes

@pollar 0.11.x. This page documents the 0.11 release line, which talks to SDK API v2. The current release is 0.12, documented under Latest. On 0.11.x the ramp methods answer 410 SDK_RAMPS_MOVED_TO_V3: ramps need 0.12. To move, read the 0.11 -> 0.12 upgrade notes.

Pollar surfaces errors in two places: the Server / SDK API (HTTP responses) and the client SDK (method outcomes and reactive state). This page documents both, plus the real error codes.

Error model

Server / SDK API responses

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

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

Some errors include extra fields (e.g. validation issues):

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

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

Client SDK

Most @pollar/core methods do not throw on operational failures. Instead they:

• Return an outcome object — e.g. buildTx, signAndSubmitTx, runTx resolve to { status: 'error', details?, resultCode? } (vs 'built' | 'success' | '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.details, result.resultCode);
}

The only error that is thrown is PollarFlowError (exported from @pollar/core), raised when a flow method is called out of order (e.g. verifying an OTP code before one was sent). Its code is always 'INVALID_FLOW':

import { PollarFlowError } from '@pollar/core';

try {
  pollar.verifyEmailCode('123456');
} catch (err) {
  if (err instanceof PollarFlowError) {
    // called the wrong step for the current AuthState
  }
}

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).

Auth, API keys & access

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

Validation & general

Wallet & funding

Co-signed wallets

Apps in co-signed custody (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'.

Trustlines

Signer rotation

Transactions

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:

Distribution

KYC & Ramps

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, authentik, wallet-adapter). The codes above are the ones an SDK or Server API integrator is most likely to encounter.

Handling errors in the SDK

import { PollarFlowError } from '@pollar/core';

// Operational failures come back as outcomes — no try/catch needed.
const result = await pollar.runTx('payment', { destination, amount, asset });
if (result.status === 'error') {
  switch (result.resultCode) {
    case 'tx_insufficient_balance':
      // not enough of the asset
      break;
    default:
      console.error(result.details);
  }
}

// Misuse of the flow API throws.
try {
  pollar.sendEmailCode('[email protected]');
} catch (err) {
  if (err instanceof PollarFlowError) {
    // wrong step for the current AuthState
  }
}

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