SDKPython
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 raisesDemoSignerOnMainnetError.- 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 withPAY_KIT_MPP_CHALLENGE_BINDING_SECRET.