> ## Documentation Index
> Fetch the complete documentation index at: https://docs.faremeter.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common errors and how to resolve them when integrating faremeter.

## 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:**

| Cause                      | Fix                                                                                                                                   |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Stale blockhash (Solana)   | The payment proof was constructed too long ago. Reduce the time between receiving requirements and submitting payment.                |
| Insufficient token balance | The payer wallet does not have enough of the required token. Fund the wallet.                                                         |
| Wrong network              | The client is signing for a different network than the server expects. Check `network` in your requirements and wallet configuration. |
| Amount mismatch            | The payment amount does not match `maxAmountRequired`. Ensure the client is using the exact amount from the requirements.             |
| Expired proof              | `maxTimeoutSeconds` 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:
   ```bash theme={null}
   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`:
   ```typescript theme={null}
   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:
  ```typescript theme={null}
  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.