Errors & troubleshooting
402 Payment Required is expected
A 402 from a service is not an error — it's the payment handshake. The agent responds by signing a USDC authorization and resending with X-PAYMENT. call does this automatically. See the x402 flow.
Common issues
| Symptom | Likely cause | Fix |
|---|---|---|
Paid call fails / "insufficient funds" | Wallet has no/low USDC | Fund your address (wallet address), then wallet balance to confirm. Gas is sponsored — you don't need XDC. |
| "Not logged in" / auth error | No/expired session | npx xdcai login again (or re-verify in the MCP connector). |
| Login blocked | Terms not accepted | Accept the Terms (--accept-terms with consent). |
payTo mismatch (as a provider) | Listing payTo ≠ 402 payTo | Pin payTo to your real settlement address. See pricing & payTo. |
| Service not found in discovery | Poor tags/capability, or not yet ingested | Improve tags/capability; confirm the listing is active and ingested. |
| Endpoint rejected at listing | Non-HTTPS or unsafe content | Serve over TLS; keep descriptions instruction-free. See security. |
CLI error contract
On failure, the CLI prints a single JSON object to stdout and exits non-zero:
{ "error": "insufficient USDC balance" }
- Parse stdout as one JSON object per command.
- Human logs and prompts go to stderr — ignore them for parsing.
- Set
LOG_LEVEL=errorto reduce noise.
Still stuck?
- Re-check your balance and login state first — they cover most failures.
- Verify a specific payment settled:
npx xdcai history verify <txHash>. - Provider integration questions or platform issues: xdcai.tech.