StripeKit - Error Handling

Every module throws typed exceptions you can catch and branch on.

Exception hierarchy

All StripeKit exceptions extend StripeKit\Exceptions\StripeKitError, itself an Exception, which exposes:

public readonly string $errorCode;
public readonly int $statusCode;
public readonly mixed $cause;

Class	`errorCode`	`statusCode`	Thrown when
`ConfigurationError`	`configuration_error`	500	`StripeKit::init()` is called with missing or invalid options.
`ValidationError`	`validation_error`	422	Input fails StripeKit's own validation before it reaches Stripe. Exposes an additional `?array $fieldErrors`.
`NotFoundError`	`not_found`	404	A requested object, such as a customer or subscription, cannot be found.
`StripeOperationError`	`stripe_operation_error`	422	Stripe itself rejects the request. `$cause` holds the original Stripe exception.
`WebhookVerificationError`	`webhook_verification_error`	400	`$kit->webhooks->process()` cannot verify the signature or payload.

StripeOperationError also exposes a static factory, StripeOperationError::fromError($error, $fallbackMessage), used internally to wrap any underlying Stripe SDK exception while preserving its message and attaching it as $cause.

Catching broadly

Since every StripeKit exception extends StripeKitError, you can catch all of them at once when you only need the normalized errorCode and statusCode, for example to return a consistent JSON error response from an API endpoint:

Error Handling

Exception hierarchy#

Catching broadly#

Exception hierarchy

Catching broadly