Error Codes

Complete reference of 35 error codes across 10 categories returned by the Wallet Service.

Error response envelopejson

{
  "data": null,
  "error": {
    "code": "ERR_WALLET_NOT_FOUND",
    "message": "Wallet not found",
    "details": null,
    "traceId": "abc123-def456"
  },
  "meta": {
    "requestId": "req_1708425600_a1b2c3d",
    "traceId": "abc123-def456",
    "timestamp": "2026-02-21T10:00:00.000Z"
  }
}

Wallet LifecycleWallet

Code	HTTP	Description	Resolution
`ERR_WALLET_NOT_FOUND`	404	Wallet not found for the given tenant	Verify wallet ID and tenant context
`ERR_WALLET_ALREADY_EXISTS`	409	Wallet already exists for this owner	Query existing wallets before creation
`ERR_WALLET_FROZEN`	403	Wallet is frozen by admin	Contact admin to unfreeze the wallet
`ERR_WALLET_CLOSED`	403	Wallet is permanently closed	Create a new wallet for the owner
`ERR_WALLET_SUSPENDED`	403	Wallet is temporarily suspended	Wait for auto-resolution or contact admin

Balance and Credit ErrorsBalance & Credits

Code	HTTP	Description	Resolution
`ERR_WALLET_INSUFFICIENT_BALANCE`	402	Insufficient balance for the operation	Top up the wallet or reduce transaction amount
`ERR_WALLET_INSUFFICIENT_CREDITS`	402	Insufficient AI credits	Purchase credit packs or upgrade subscription
`ERR_WALLET_CREDIT_LIMIT_EXCEEDED`	402	Credit limit exceeded for post-paid account	Clear outstanding balance or request limit increase

Transaction ErrorsTransactions

Code	HTTP	Description	Resolution
`ERR_WALLET_TRANSACTION_NOT_FOUND`	404	Transaction not found for the tenant	Verify transaction ID and tenant context
`ERR_WALLET_TRANSACTION_ALREADY_COMPLETED`	409	Transaction already in terminal state	Check transaction status; no action needed
`ERR_WALLET_TRANSACTION_ALREADY_REFUNDED`	409	Transaction already fully refunded	Check refund history for partial refund options
`ERR_WALLET_REFUND_AMOUNT_EXCEEDED`	400	Refund exceeds original transaction amount	Query remaining refundable amount first
`ERR_WALLET_IDEMPOTENCY_CONFLICT`	409	Same Idempotency-Key with different body	Use unique key per operation; keys expire after 24h

Escrow ErrorsEscrow

Code	HTTP	Description	Resolution
`ERR_WALLET_ESCROW_NOT_FOUND`	404	Escrow not found for the tenant	Verify escrow ID and tenant context
`ERR_WALLET_ESCROW_NOT_FUNDED`	400	Escrow not in funded state	Fund the escrow before attempting release
`ERR_WALLET_ESCROW_EXPIRED`	400	Escrow has expired	Funds auto-returned to payer; create new escrow
`ERR_WALLET_ESCROW_DISPUTED`	409	Escrow is under dispute	Wait for dispute resolution by admin

Payment Method ErrorsPayment Methods

Code	HTTP	Description	Resolution
`ERR_WALLET_PAYMENT_METHOD_NOT_FOUND`	404	Payment method not found for the wallet	Verify payment method ID and wallet scope
`ERR_WALLET_PAYMENT_METHOD_INACTIVE`	400	Payment method is deactivated or pending	Complete verification or re-register
`ERR_WALLET_PAYMENT_METHOD_VERIFICATION_FAILED`	400	Payment method verification failed	Check details.reason; retry with correct info

Split Payment ErrorsSplit Payments

Code	HTTP	Description	Resolution
`ERR_WALLET_SPLIT_PAYMENT_NOT_FOUND`	404	Split payment not found	Verify split payment ID and tenant context
`ERR_WALLET_SPLIT_AMOUNT_MISMATCH`	400	Split amounts do not sum to total	Use integer arithmetic (cents) to avoid rounding

FX Rate ErrorsFX Rates

Code	HTTP	Description	Resolution
`ERR_WALLET_FX_RATE_NOT_FOUND`	404	Exchange rate not found for currency pair	Verify ISO 4217 codes and supported pairs
`ERR_WALLET_FX_RATE_INVALID`	400	Exchange rate data is expired or invalid	Retry; upstream FX provider may be recovering

Authentication and AuthorizationAuth & Tenant

Code	HTTP	Description	Resolution
`ERR_WALLET_TENANT_REQUIRED`	400	Tenant ID missing from request	Include x-tenant-id header or valid JWT tenant claim
`ERR_WALLET_UNAUTHORIZED`	401	Missing or invalid JWT token	Obtain fresh token from auth-svc /login
`ERR_WALLET_FORBIDDEN`	403	Insufficient permissions	Request required role from admin

Rate LimitingRate Limiting

Code	HTTP	Description	Resolution
`ERR_WALLET_RATE_LIMITED`	429	Rate limit exceeded	Implement exponential backoff; check Retry-After header

Internal and InfrastructureInfrastructure

Code	HTTP	Description	Resolution
`ERR_WALLET_BAD_REQUEST`	400	Malformed request or validation failure	Check request body against API docs
`ERR_WALLET_CONFLICT`	409	General conflict (constraint violation)	Check for duplicate keys or state conflicts
`ERR_WALLET_INTERNAL_ERROR`	500	Unhandled internal error	Retry; report with request_id if persistent
`ERR_WALLET_SERVICE_UNAVAILABLE`	503	Service temporarily unavailable	Retry with exponential backoff
`ERR_WALLET_TIMEOUT`	504	Upstream service timeout	Reduce complexity or retry
`ERR_WALLET_BOOTSTRAP_FAILED`	503	Lambda bootstrap failed	Retry; cold start may still be in progress