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.

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.

Error types

Boot-time safety rails

On this page