x402 facilitator
Troubleshooting
The errors you'll actually hit, and the fix for each.
| Error | What it means | Fix |
|---|---|---|
already_settled | This exact payment was already paid. | Create a new payment. Nothing is wrong. |
INVALID_SIGNATURE (self-hosted) | The fee-payer key doesn't control the account. | Use the key the ledger holds for that account. Self-hosted instances refuse to start on this. |
TOKEN_NOT_ASSOCIATED_TO_ACCOUNT | The buyer or payTo account can't hold USDC yet. | Associate USDC with the account, or turn on automatic token associations. |
INSUFFICIENT_TOKEN_BALANCE | The buyer doesn't have enough USDC. | Top up the buyer. |
invalid_exact_hedera_payload_transaction_could_not_be_decoded | The payment wasn't built by an x402 Hedera client. | Use @x402/hedera's client scheme. |
Expired payment / TRANSACTION_EXPIRED | The buyer signed too long before settling. Hedera transactions are valid for about 3 minutes. | Sign and settle straight away. |
fee_payer_not_managed_by_facilitator | extra.feePayer isn't one of ours. | Read the fee payer from GET /supported; don't hard-code it. |
ERC20: transfer amount exceeds balance | Base buyer has too little USDC. | Top up. On Base Sepolia get it from faucet.circle.com. |
Simulation failed: AccountNotFound | A Solana account in the transfer doesn't exist yet, often the receiver's USDC account. | Send the receiver any USDC once, so its token account exists. |
400 with a message | The request body is malformed. | Read the message; it names the field. Don't retry. |
503 Facilitator unavailable | The instance can't start or a fee payer is low. | Check GET /health. |