# Errors

> The pay-kit error types and the boot-time safety rails that catch misconfiguration before any traffic.

All pay-kit errors extend `PayKitError`, so you can catch the base class to handle any of them. Configuration problems throw when `createPayKit` runs — at boot, before serving traffic — while proof and protocol errors surface per request during verification.

```ts
import { PayKitError, ConfigurationError } from '@solana/pay-kit';

try {
  pay = await createPayKit({
    /* … */
  });
} catch (err) {
  if (err instanceof ConfigurationError) {
    // a gate, fee, or operator setting is invalid — fix config and restart
  }
}
```

## Error types

| Error                       | When it throws                                                                                                |
| --------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `PayKitError`               | Base class for every error below.                                                                             |
| `ConfigurationError`        | Invalid gate, fee, or operator config (base class for the boot-time errors below).                            |
| `DemoSignerOnMainnetError`  | `solana_mainnet` combined with the published demo signer — refused so real funds never route to a public key. |
| `ProtocolIncompatibleError` | A gate's `accept` can't support its shape — e.g. `accept: ['x402']` on a fee-bearing gate (fees need MPP).    |
| `ProtocolNotSupportedError` | A requested protocol has no shipped adapter.                                                                  |
| `MixedCurrenciesError`      | A gate's fees and amount don't share one currency.                                                            |
| `UnknownGateError`          | A gate name was referenced that isn't in the `pricing` catalogue.                                             |
| `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.                                                           |
| `PaymentRequiredError`      | No valid payment was present where one was required.                                                          |

## Boot-time safety rails

Outside localnet, two checks fire when `createPayKit` runs:

- `solana_mainnet` plus the published demo signer throws `DemoSignerOnMainnetError`.
- A missing `mpp.challengeBindingSecret` throws — provide it in `createPayKit` or via `PAY_KIT_MPP_SECRET` so the HMAC binding challenges stays stable across restarts. On localnet an ephemeral secret is generated with a warning.