Skip to main content

​
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:
CauseFix
Stale blockhash (Solana)The payment proof was constructed too long ago. Reduce the time between receiving requirements and submitting payment.
Insufficient token balanceThe payer wallet does not have enough of the required token. Fund the wallet.
Wrong networkThe client is signing for a different network than the server expects. Check network in your requirements and wallet configuration.
Amount mismatchThe payment amount does not match maxAmountRequired. Ensure the client is using the exact amount from the requirements.
Expired proofmaxTimeoutSeconds elapsed between proof construction and settlement. Retry the flow.

​
”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.