# Errors

> The solana_pay_kit exception hierarchy raised at configure/boot time, and how per-request payment failures become the 402 response.

All solana_pay_kit exceptions derive from `PayKitError`. Configuration problems raise at `configure` / boot time — before serving traffic — while proof failures raise during verification and are translated into the `402` response by the framework shim (your view only runs once a payment verifies).

## Exception types

| Exception                   | When it raises                                                                                    |
| --------------------------- | ------------------------------------------------------------------------------------------------- |
| `PayKitError`               | Base class for every exception below.                                                             |
| `ConfigurationError`        | Invalid config, gate, or fee (base class for the boot-time errors).                               |
| `DemoSignerOnMainnetError`  | The demo signer was used on `solana_mainnet` — refused so real funds never route to a public key. |
| `MixedCurrenciesError`      | A gate's fees and amount don't share one denomination.                                            |
| `ProtocolIncompatibleError` | A fee-bearing gate was restricted to `accept=(Protocol.X402,)`; fees need MPP.                    |
| `InvalidKeyError`           | Key material couldn't be parsed into a signer.                                                    |
| `InvalidProofError`         | A submitted payment credential failed verification.                                               |
| `ChallengeExpiredError`     | A payment arrived against an expired 402 challenge (subclass of `InvalidProofError`).             |
| `PaymentRequiredError`      | No valid payment was present where one was required.                                              |
| `ProtocolNotSupportedError` | A requested protocol has no registered adapter.                                                   |

## Boot-time safety rails

- `network="solana_mainnet"` with the published demo signer raises `DemoSignerOnMainnetError`.
- A missing MPP challenge-binding secret is resolved from the environment (falling back to `./.env`, generating and persisting one if neither exists) so the HMAC stays stable across restarts. Override with `PAY_KIT_MPP_CHALLENGE_BINDING_SECRET`.