Errors
Every error @radonsdk/payments can throw, its stable .code, and when it happens. Branch on .code, never on message text.
Every error extends PaymentError and carries a stable string .code. Branch
on .code, not on the human-readable message (messages may change; codes
won't).
import { PaymentError } from "@radonsdk/payments";
try {
await payments.charge({ amount: money(1999, "USD"), customer: { email } });
} catch (err) {
if (err instanceof PaymentError) {
switch (err.code) {
case "license_required": return upsellPro();
case "webhook_signature_invalid": return respond(400);
case "currency_mismatch": return showCouponError();
default: throw err;
}
}
}Error catalog
InvalidConfigErrorcode: "invalid_config"Bad or ambiguous config — no providers, or defaultProvider unset with several configured.
ProviderNotFoundErrorcode: "provider_not_found"Referenced a slug that isn't registered.
ProviderNotConfiguredErrorcode: "provider_not_configured"Used a provider that wasn't listed in providers.
LicenseRequiredErrorcode: "license_required"Used a Pro provider without a verified license. Fires before any network call.
LicenseInvalidErrorcode: "license_invalid"The license key is invalid, expired, or the verifier was unreachable (fails closed).
UnsupportedOperationErrorcode: "unsupported_operation"The provider can't do this operation (e.g. Klarna webhooks, a provider without subscriptions). Carries .provider and .operation.
AuthenticationErrorcode: "authentication_failed"The provider rejected the credentials (HTTP 401/403).
ProviderApiErrorcode: "provider_error"The provider returned an error. Carries .provider, .status (HTTP), .providerCode, and .raw.
NetworkErrorcode: "network_error"The request to the provider failed at the transport level.
WebhookSignatureErrorcode: "webhook_signature_invalid"A webhook signature didn't verify — respond 400. Usually means the body wasn't the raw bytes.
CouponNotFoundErrorcode: "coupon_not_found"No coupon with that code.
CouponInvalidErrorcode: "coupon_invalid"The coupon exists but can't apply here.
CouponExpiredErrorcode: "coupon_expired"Past expiresAt.
CouponLimitReachedErrorcode: "coupon_limit_reached"maxRedemptions reached.
CurrencyMismatchErrorcode: "currency_mismatch"A fixed-amount coupon's currency doesn't match the charge currency.
Provider errors carry context
ProviderApiError exposes the provider's own status, providerCode, and the
raw payload — log these when debugging a specific processor.