Error Codes

Proxy API Errors

Code	HTTP Status	Meaning	Resolution
`VALIDATION_ERROR`	400	Request body failed Zod validation	Check required fields and formats
`INVALID_AMOUNT`	400	Amount must be positive	Provide a positive USDC amount
`AUTH_REQUIRED`	401	Missing or invalid JWT	Authenticate via `/api/auth/challenge` + `/api/auth/verify`
`INSUFFICIENT_BALANCE`	400	Agent balance too low for payment/withdrawal	Deposit more USDC first
`ZK_NOT_CONFIGURED`	503	ZK Pool Service not initialized	Ensure `POOL_SECRET` and `POOL_CONTRACT_ID` are set
`PREPARE_EXPIRED`	400	Deposit prepare ID not found or expired	Call `/api/deposit/prepare` again
`PREPARE_FAILED`	500	ZK proof generation or simulation failed	Check proxy logs for circuit/contract errors
`SEND_FAILED`	502	Transaction rejected by Stellar network	Check account funding and sequence numbers
`TX_FAILED`	502	Transaction failed on-chain after submission	Check Stellar Expert for diagnostic events
`WITHDRAW_TX_FAILED`	502	Atomic ZK withdrawal failed	Check proxy logs — likely proof or nullifier issue
`DEPOSIT_FAILED`	500	Deposit processing error	Check proxy logs for detailed error
`PAYMENT_FAILED`	500	x402 payment routing failed	Verify service is running and balance is sufficient
`BATCH_NOT_CONFIGURED`	503	Batch operator not initialized	Ensure `POOL_SECRET` is set
`USE_ATOMIC_DEPOSIT`	400	Non-localhost request to legacy deposit endpoint	Use `/api/deposit/prepare` + `/api/deposit/submit` instead

Error	Contract	Meaning
Invalid proof	Pool	Groth16 verification failed — proof is malformed or doesn’t match public inputs
Unknown root	Pool	The Merkle root in the proof doesn’t match any root in the contract’s ring buffer
Nullifier already used	Pool	Double-spend attempt — this nullifier was already consumed
ASP membership check failed	Pool	Prover is not in the ASP membership tree
Insufficient pool balance	Pool	Pool doesn’t have enough USDC for the withdrawal amount
Simulation failed	RPC	The transaction would fail if submitted — check diagnostic events for the reason