Troubleshooting

Common Issues

1

"402 Payment Required" but I paid!

Cause: Payment signature invalid or expired

Fix:

example.js

// Ensure wallet is on correct network
const wallet = createWalletClient({
  chain: baseSepolia, // Must match gateway network!
  // ...
});

// Check facilitator URL
facilitatorUrl: 'https://x402.org/facilitator'; // Correct

2

"Gateway not found"

Cause: Subdomain doesn't exist or typo

Fix:

example.sh

# Check your gateways
GET /api/gateways

# Use exact subdomain from response
https://yourapp-a3f9k2.gate402.io  # ✅ Correct
https://yourapp.gate402.io         # ❌ Wrong (no random suffix)

3

"Origin server unreachable"

Cause: Your API is down or URL is wrong

Fix:

example.sh

# Test origin URL directly
curl https://api.yourapp.com/endpoint

# If it works, check Gateway config
GET /api/gateways/:id

# Verify originUrl is correct

4

Payments not showing in wallet

Cause: Wrong network or address

Fix:

example.sh

# Check gateway config
GET /api/gateways/:id

# Verify:

# 1. evmAddress is YOUR wallet

# 2. paymentNetwork matches your wallet's network

# 3. Check blockchain explorer for transactions

5

"Invalid secret token"

Cause: Origin server rejecting requests

Fix:

example.js

// In your origin API, accept Gate402 requests:
app.use((req, res, next) => {
  const secret = req.headers['x-gate402-secret'];

  // Allow if secret matches OR if no secret required
  if (!process.env.GATE402_SECRET || secret === process.env.GATE402_SECRET) {
    return next();
  }

  res.status(403).json({ error: 'Forbidden' });
});

Error Codes

Code	Meaning	Solution
402	Payment Required	Send payment with PAYMENT-SIGNATURE header
403	Forbidden	Check secret token or IP whitelist
404	Gateway Not Found	Verify subdomain is correct
429	Too Many Requests	Slow down or upgrade plan
500	Server Error	Check origin API is responding
502	Bad Gateway	Origin API returned invalid response
504	Gateway Timeout	Origin API too slow (>30s)

FAQ

Do I need to change my API code?

No! Gate402 is a proxy. Your API stays exactly the same.

Where do payments go?

Directly to your wallet address (evmAddress). Gate402 never holds your money.

What if my API is private/localhost?

Use ngrok or similar to expose it, or deploy Gate402 on your own infrastructure.

Can I set different prices per endpoint?

Not yet (coming soon!). Currently one price for all requests.

What currencies are supported?

USDC on Base and Solana. More coming soon.

Are there platform fees?

Free tier: 1,000 requests/month. Paid plans coming soon.

Can consumers pay with credit cards?

Not yet. They need a crypto wallet with USDC.

Is this production-ready?

Currently in beta. Use testnet for now. Mainnet support coming Q1 2025.