Troubleshooting

​

402 Payment Required with no payment options

Symptom: Your client receives a 402 response but the accepts array is empty or missing. Cause: The facilitator’s /accepts endpoint could not enrich your payment requirements. This usually means the facilitator does not support the scheme, network, or asset you configured. Fix:

1. Check your accepts configuration against the facilitator’s supported list: GET https://facilitator.corbits.dev/supported
2. Ensure you are using the "exact" scheme. The Corbits hosted facilitator only supports "exact".
3. Verify the network name matches exactly (e.g., "devnet", "base-sepolia").

​

”Invalid payment” or settlement failure

Symptom: The client sends a valid-looking payment header (X-PAYMENT or PAYMENT-SIGNATURE) but the facilitator rejects it. Possible causes:

​

”Facilitator unreachable” or network errors

Symptom: The middleware throws a network error when contacting the facilitator. Fix:

1. Confirm the facilitatorURL is correct. The default is https://facilitator.corbits.dev.
2. Check that your server can reach the facilitator (firewall, DNS, proxy settings).
3. If running your own facilitator, verify it is running and the /supported endpoint responds.

​

Client does not retry after 402

Symptom: The client receives 402 Payment Required but does not make a second request with payment. Possible causes:

• No wallet configured. The client needs at least one wallet added via payer.addLocalWallet() before calling payer.fetch().
• No compatible payment method. The client’s wallet does not support any of the schemes/networks in the accepts array. For example, a Solana wallet cannot fulfill an EVM-only requirement.
• Using plain fetch instead of payer.fetch. The standard fetch API does not handle 402 responses. Use @faremeter/rides or @faremeter/fetch.

​

”Module not found” for @faremeter/* packages

Symptom: Import errors when requiring faremeter packages. Fix:

1. Install the specific sub-package you need. Faremeter uses scoped sub-path imports:
   pnpm add @faremeter/middleware  # for middleware
   pnpm add @faremeter/info        # for payment requirement helpers
   pnpm add @faremeter/rides       # for the client SDK
   
2. Use the correct import path. For example, use @faremeter/info/solana not @faremeter/info:
   import { x402Exact } from "@faremeter/info/solana"    // correct
   import { x402Exact } from "@faremeter/info"            // incorrect
   

​

Solana: “Transaction simulation failed”

Symptom: The facilitator returns an error mentioning transaction simulation failure. Common causes:

• Insufficient SOL for fees. The facilitator’s fee payer account needs SOL to cover transaction fees. If you are running your own facilitator, fund the fee payer keypair.
• Token account does not exist. The payTo address must have an associated token account for the asset. Create one if it does not exist.
• Wrong mint address. Double-check that the mint address in your facilitator handler matches the token you intend to accept.

​

EVM: “Execution reverted”

Symptom: The facilitator returns an EVM execution revert error during settlement. Common causes:

• Insufficient token allowance or balance. The payer must hold enough of the ERC-20 token.
• Wrong chain ID. Ensure the chain configuration in your facilitator handler matches the network the client is signing for.
• Contract address mismatch. The EIP-712 domain parameters must match the actual token contract on the target chain.

​

Debugging tips

• Enable logging. Use @faremeter/logs to get structured logs from both client and server:
  import { getLogger } from "@faremeter/logs"
  const logger = await getLogger(["server"])
  
• Check the facilitator response. The facilitator returns detailed error messages in its JSON response body. Log the full response when debugging settlement failures.
• Test with devnet first. Always develop against devnet (Solana) or base-sepolia (EVM) before switching to mainnet.
• Inspect the payment header. Base64-decode the X-PAYMENT (v1) or PAYMENT-SIGNATURE (v2) header value to see the raw payment payload and verify the structure matches expectations.