🚨 Error Codes Dictionary

Stuck? Read this first. This page lists every error you may encounter, with causes and solutions, strictly mapped to the PayNode SSoT.

Client / SDK Errors

Error Code	SDK	Common Cause	Solution
`insufficient_funds`	JS / PY	Wallet lacks USDC or ETH for gas	Fund your wallet via testnet faucet or ensure mainnet balance
`token_not_accepted`	JS / PY	Token address is not in the SDK whitelist	Verify you’re using the official USDC address. See Token Whitelist
`amount_too_low`	JS / PY	Payment is below 1000 (0.001 USDC)	Protocol minimum is 1000 to prevent dust exploits. Increase payment amount.
`rpc_error`	JS / PY	Failed to connect to any provided RPC nodes	Check your RPC URLs or network connectivity.
`internal_error`	JS / PY	An unexpected error in the SDK	Report to the PayNode team with stack trace.

Error Code	HTTP	Common Cause	Solution
`missing_receipt`	`402`	Request lacks `X-402-Payload` or `x-paynode-receipt`	Ensure client uses latest SDK and provides the required headers.
`invalid_receipt`	`403`	Payload format invalid or malformed	(1) Check if tx is still pending (2) Verify RPC node is synced (3) Check network match
`duplicate_transaction`	`403`	Transaction already consumed (replay attack)	Each payment is valid for exactly one request. Do not reuse.
`transaction_not_found`	`403`	TxHash returns null receipt from RPC	Transaction may not be mined yet. Wait and retry.
`transaction_failed`	`402`	Transaction reverted on-chain (status = 0)	Check Basescan for revert reason. Common: insufficient allowance or balance.
`wrong_contract`	`403`	Event was not emitted by official contract	Verify the router address in `X-402-Required` matches the official PayNode Router.
`order_mismatch`	`403`	Order ID in payload does not match requested	Ensure `x-paynode-order-id` (or `X-402-Order-Id`) matches the payload’s orderId.

“402 but Agent won’t pay” — Check Agent wallet has ETH (gas) + USDC on the correct network.
“403 invalid_receipt” — Are both sides on the same network? (mainnet vs sepolia).
“token_not_accepted” — Are you using a custom token? Add it to acceptedTokens config.
“duplicate_transaction” — Each payment can only unlock one request. Generate a new payment.
“Nonce too low” — In Python, ensure you’re using a single PayNodeAgentClient instance (thread-safe).