Error Codes

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

Trustlines

Transactions

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('user@example.com');
} 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'.