Add rate-limit/cooldown to Stripe API requests after 401 errors (#4497)

* Use the Database_Cache as rate limit for the 401 error count
* Reset the invalid key error count cache after reconnect
* Invalidate Account Data cache when in 401 cooldown

Author: diegocurbelo

changelog.txt

@@ -13,7 +13,9 @@
 * Dev - Fix failing test cases associated with WooCommerce 10.0.x
 * Fix - Prevent multiple save appearance AJAX calls on Block Checkout
 * Fix - Fix required field error message and PHP warning for custom checkout fields that don't have a label
+* Update - Improve Stripe API connector logging to include request/response context
 * Fix - Fix fatal when processing setup intents for free subscriptions via webhooks
+* Fix - Prevent Stripe API calls after several consecutive 401 (Unauthorized) responses
 
 = 9.7.0 - 2025-07-21 =
 * Update - Removes BNPL payment methods (Klarna and Affirm) when other official plugins are active

includes/class-wc-stripe-api.php

@@ -16,6 +16,28 @@ class WC_Stripe_API {
 	const ENDPOINT           = 'https://api.stripe.com/v1/';
 	const STRIPE_API_VERSION = '2024-06-20';
 
+	/**
+	 * The invalid API key error count cache key.
+	 *
+	 * @var string
+	 */
+	public const INVALID_API_KEY_ERROR_COUNT_CACHE_KEY = 'invalid_api_key_error_count';
+
+	/**
+	 * The invalid API key error count cache timeout.
+	 * This is the delay in seconds enforced for Stripe API calls after the consecutive error count threshold is reached.
+	 *
+	 * @var int
+	 */
+	protected const INVALID_API_KEY_ERROR_COUNT_CACHE_TIMEOUT = 2 * HOUR_IN_SECONDS;
+
+	/**
+	 * The invalid API key error count threshold.
+	 *
+	 * @var int
+	 */
+	protected const INVALID_API_KEY_ERROR_COUNT_THRESHOLD = 5;
+
 	/**
 	 * Secret API Key.
 	 *
@@ -265,6 +287,20 @@ public static function request( $request, $api = 'charges', $method = 'POST', $w
 	 * @param string $api
 	 */
 	public static function retrieve( $api ) {
+		// If keep count of consecutive 401 errors, and it exceeds INVALID_API_KEY_ERROR_COUNT_THRESHOLD,
+		// we return null until the cache expires (INVALID_API_KEY_ERROR_COUNT_CACHE_TIMEOUT) or the keys are updated.
+		$invalid_api_key_error_count = WC_Stripe_Database_Cache::get( self::INVALID_API_KEY_ERROR_COUNT_CACHE_KEY );
+		if ( ! empty( $invalid_api_key_error_count ) && self::INVALID_API_KEY_ERROR_COUNT_THRESHOLD <= $invalid_api_key_error_count ) {
+			// We skip logging the error here because when there is no Account cache,
+			// the instantiation of the UPE gateway triggers a call to this method for
+			// every available payment method. This would result in excessive log entries
+			// which is not useful.
+			// We only log the error when the count exceeds the threshold for the first time.
+
+			// The UI expects a null response (and not an error) in case of invalid API keys.
+			return null;
+		}
+
 		WC_Stripe_Logger::log( "{$api}" );
 
 		$response = wp_safe_remote_get(
@@ -281,7 +317,29 @@ public static function retrieve( $api ) {
 			// Stripe redacts API keys in the response.
 			WC_Stripe_Logger::log( "Error: GET {$api} returned a 401" );
 
+			++$invalid_api_key_error_count;
+			WC_Stripe_Database_Cache::set( self::INVALID_API_KEY_ERROR_COUNT_CACHE_KEY, $invalid_api_key_error_count, self::INVALID_API_KEY_ERROR_COUNT_CACHE_TIMEOUT );
+
+			if ( $invalid_api_key_error_count >= self::INVALID_API_KEY_ERROR_COUNT_THRESHOLD ) {
+				WC_Stripe_Logger::error(
+					'Invalid API keys request rate limit exceeded',
+					[
+						'count'      => $invalid_api_key_error_count,
+						'next_retry' => date_i18n( 'Y-m-d H:i:sP', time() + self::INVALID_API_KEY_ERROR_COUNT_CACHE_TIMEOUT ),
+					]
+				);
+
+				// We need to invalidate the Account Data cache here, so that the UI shows the "Connect to Stripe" button.
+				WC_Stripe_Database_Cache::delete( WC_Stripe_Account::ACCOUNT_CACHE_KEY );
+			}
+
 			return null; // The UI expects this empty response in case of invalid API keys.
+
+		}
+
+		// We got a valid, non-401 response, so clear the invalid API key count if it is present.
+		if ( null !== $invalid_api_key_error_count ) {
+			WC_Stripe_Database_Cache::delete( self::INVALID_API_KEY_ERROR_COUNT_CACHE_KEY );
 		}
 
 		if ( is_wp_error( $response ) || empty( $response['body'] ) ) {

includes/connect/class-wc-stripe-connect.php

@@ -180,6 +180,7 @@ private function save_stripe_keys( $result, $type = 'connect', $mode = 'live' )
 			// Enable ECE for new connections.
 			$this->enable_ece_in_new_accounts();
 
+			WC_Stripe_Database_Cache::delete( WC_Stripe_API::INVALID_API_KEY_ERROR_COUNT_CACHE_KEY );
 			WC_Stripe_Helper::update_main_stripe_settings( $options );
 
 			// Similar to what we do for webhooks, we save some stats to help debug oauth problems.

readme.txt

@@ -124,5 +124,6 @@ If you get stuck, you can ask for help in the [Plugin Forum](https://wordpress.o
 * Fix - Prevent multiple save appearance AJAX calls on Block Checkout
 * Fix - Fix required field error message and PHP warning for custom checkout fields that don't have a label
 * Fix - Fix fatal when processing Boleto setup intents via webhooks
+* Fix - Prevent Stripe API calls after several consecutive 401 (Unauthorized) responses
 
 [See changelog for full details across versions](https://raw.githubusercontent.com/woocommerce/woocommerce-gateway-stripe/trunk/changelog.txt).

tests/phpunit/Admin/Migrations/WC_Stripe_Subscriptions_Repairer_Legacy_SEPA_Tokens_Test.php

@@ -7,6 +7,8 @@
 use WooCommerce\Stripe\Tests\Helpers\UPE_Test_Helper;
 use WC_Gateway_Stripe_Sepa;
 use WC_Logger;
+use WC_Stripe_API;
+use WC_Stripe_Database_Cache;
 use WC_Stripe_Helper;
 use WC_Stripe_Subscriptions_Legacy_SEPA_Token_Update;
 use WC_Stripe_UPE_Payment_Gateway;
@@ -87,6 +89,16 @@ public function set_up() {
 		WC_Stripe_Helper::update_main_stripe_settings( [ 'test_connection_type' => 'connect' ] );
 	}
 
+	public function tear_down() {
+		// The tests in this file do not mock ALL the calls to the Stripe API, and as we use mocked API keys they trigger the 401 rate-limiter,
+		// this is not a problem for these tests as they don't depend on the reponses.
+		//
+		// TODO: Remove this once we've mocked all calls to the Stripe API (either using the pre_http_request filter, or by using a mocked WC_Stripe_API class).
+		WC_Stripe_Database_Cache::delete( WC_Stripe_API::INVALID_API_KEY_ERROR_COUNT_CACHE_KEY );
+
+		parent::tear_down();
+	}
+
 	/**
 	 * For the repair to be scheduled, WC_Subscriptions must be active, UPE must be enabled, and the action must not have been scheduled before.
 	 *

tests/phpunit/Admin/WC_REST_Stripe_Settings_Controller_GB_Test.php

@@ -6,6 +6,8 @@
 use WooCommerce\Stripe\Tests\Helpers\UPE_Test_Helper;
 use WC_Gateway_Stripe;
 use WC_REST_Stripe_Settings_Controller;
+use WC_Stripe_API;
+use WC_Stripe_Database_Cache;
 use WC_Stripe_Feature_Flags;
 use WC_Stripe_Helper;
 use WC_Stripe_Payment_Methods;
@@ -106,6 +108,17 @@ public function set_up() {
 		self::$gateway = WC()->payment_gateways()->payment_gateways()[ WC_Gateway_Stripe::ID ];
 	}
 
+	public function tear_down() {
+		// The tests in this file do not mock ALL the calls to the Stripe API, and as we use mocked API keys they trigger the 401 rate-limiter,
+		// this is not a problem for these tests as they don't depend on the reponses.
+		//
+		// TODO: Remove this once we've mocked all calls to the Stripe API (either using the pre_http_request filter, or by using a mocked WC_Stripe_API class).
+		WC_Stripe_Database_Cache::delete( WC_Stripe_API::INVALID_API_KEY_ERROR_COUNT_CACHE_KEY );
+
+		parent::tear_down();
+	}
+
+
 	public function test_get_settings_returns_available_payment_method_ids_for_gb() {
 		$expected_method_ids = [
 			WC_Stripe_Payment_Methods::CARD,

tests/phpunit/PaymentMethods/WC_Stripe_UPE_Payment_Gateway_Test.php

@@ -42,6 +42,7 @@
 use WC_Stripe_UPE_Payment_Method_Wechat_Pay;
 use WC_Subscriptions_Helpers;
 use MockAction;
+use WC_Stripe_API;
 use WooCommerce\Stripe\Tests\Helpers\WC_Helper_Order;
 use WooCommerce\Stripe\Tests\Helpers\WC_Helper_Token;
 use WooCommerce\Stripe\Tests\WC_Mock_Stripe_API_Unit_Test_Case;
@@ -247,13 +248,20 @@ public function set_up() {
 	}
 
 	public function tear_down() {
-		parent::tear_down();
 		delete_option( WC_Stripe_Feature_Flags::LPM_ACH_FEATURE_FLAG_NAME );
 		delete_option( WC_Stripe_Feature_Flags::LPM_ACSS_FEATURE_FLAG_NAME );
 		delete_option( WC_Stripe_Feature_Flags::LPM_BACS_FEATURE_FLAG_NAME );
 		delete_option( WC_Stripe_Feature_Flags::LPM_BLIK_FEATURE_FLAG_NAME );
 		delete_option( WC_Stripe_Feature_Flags::AMAZON_PAY_FEATURE_FLAG_NAME );
 		delete_option( WC_Stripe_Feature_Flags::LPM_BECS_DEBIT_FEATURE_FLAG_NAME );
+
+		// The tests in this file do not mock ALL the calls to the Stripe API, and as we use mocked API keys they trigger the 401 rate-limiter,
+		// this is not a problem for these tests as they don't depend on the reponses.
+		//
+		// TODO: Remove this once we've mocked all calls to the Stripe API (either using the pre_http_request filter, or by using a mocked WC_Stripe_API class).
+		WC_Stripe_Database_Cache::delete( WC_Stripe_API::INVALID_API_KEY_ERROR_COUNT_CACHE_KEY );
+
+		parent::tear_down();
 	}
 
 	/**

tests/phpunit/WC_Stripe_API_Test.php

@@ -2,7 +2,9 @@
 
 namespace WooCommerce\Stripe\Tests;
 
+use ReflectionClass;
 use WC_Stripe_API;
+use WC_Stripe_Database_Cache;
 use WC_Stripe_Helper;
 use WP_UnitTestCase;
 
@@ -37,14 +39,21 @@ public function set_up() {
 		$stripe_settings['secret_key']      = self::LIVE_SECRET_KEY;
 		$stripe_settings['test_secret_key'] = self::TEST_SECRET_KEY;
 		WC_Stripe_Helper::update_main_stripe_settings( $stripe_settings );
+
+		// Reset the invalid API keys count cache.
+		WC_Stripe_Database_Cache::delete( WC_Stripe_API::INVALID_API_KEY_ERROR_COUNT_CACHE_KEY );
 	}
 
 	/**
 	 * Tear down environment after tests.
 	 */
 	public function tear_down() {
+		// Reset the invalid API keys count cache.
+		WC_Stripe_Database_Cache::delete( WC_Stripe_API::INVALID_API_KEY_ERROR_COUNT_CACHE_KEY );
+
 		WC_Stripe_Helper::delete_main_stripe_settings();
 		WC_Stripe_API::set_secret_key( null );
+
 		parent::tear_down();
 	}
 
@@ -117,6 +126,64 @@ public function test_retrieve_makes_api_call_when_api_keys_are_valid() {
 		remove_filter( 'pre_http_request', [ $this, 'mock_successful_response' ] );
 	}
 
+	/**
+	 * Test WC_Stripe_API::retrieve() returns null without API call after raeching the max threshold.
+	 */
+	public function test_retrieve_returns_null_without_api_call_after_threshold() {
+		$call_count = 0;
+
+		// Mock HTTP to always return 401 and increment the counter.
+		add_filter(
+			'pre_http_request',
+			function () use ( &$call_count ) {
+				$call_count++;
+				return $this->mock_unauthorized_response();
+			}
+		);
+
+		$stripe_api_class = new ReflectionClass( WC_Stripe_API::class );
+		$threshold  = $stripe_api_class->getConstant( 'INVALID_API_KEY_ERROR_COUNT_THRESHOLD' );
+
+		// Call retrieve up to the threshold, each should make an HTTP call.
+		for ( $i = 0; $i < $threshold; $i++ ) {
+			WC_Stripe_API::retrieve( 'test_endpoint' );
+		}
+		$this->assertEquals( $threshold, $call_count, 'Should have made HTTP calls up to the threshold.' );
+
+		// Now, the next call should NOT make an HTTP call, but return null immediately.
+		$result = WC_Stripe_API::retrieve( 'test_endpoint' );
+		$this->assertNull( $result, 'Expected null after reaching invalid API key threshold.' );
+		$this->assertEquals( $threshold, $call_count, 'Should not make another HTTP call after threshold is reached.' );
+
+		remove_all_filters( 'pre_http_request' );
+		WC_Stripe_Database_Cache::delete( WC_Stripe_API::INVALID_API_KEY_ERROR_COUNT_CACHE_KEY );
+	}
+
+	/**
+	 * Test WC_Stripe_API::retrieve() resets the invalid API key count on successful response.
+	 */
+	public function test_retrieve_resets_invalid_api_key_count_on_successful_response() {
+		// 1. Mock a 401 response for the first call.
+		add_filter( 'pre_http_request', [ $this, 'mock_unauthorized_response' ] );
+
+		// First call: should set the cache count to 1.
+		WC_Stripe_API::retrieve( 'test_endpoint' );
+		$count = WC_Stripe_Database_Cache::get( WC_Stripe_API::INVALID_API_KEY_ERROR_COUNT_CACHE_KEY );
+		$this->assertEquals( 1, $count, 'Cache count should be 1 after first 401.' );
+
+		remove_all_filters( 'pre_http_request' );
+
+		// 2. Mock a 200 response for the second call.
+		add_filter( 'pre_http_request', [ $this, 'mock_successful_response' ] );
+
+		// Second call: should delete the cache.
+		WC_Stripe_API::retrieve( 'test_endpoint' );
+		$count = WC_Stripe_Database_Cache::get( WC_Stripe_API::INVALID_API_KEY_ERROR_COUNT_CACHE_KEY );
+		$this->assertNull( $count, 'Cache should be deleted after a successful response.' );
+
+		remove_all_filters( 'pre_http_request' );
+	}
+
 	/**
 	 * Helper method to mock a successful API response.
 	 */
@@ -129,4 +196,17 @@ public function mock_successful_response() {
 			'body'     => json_encode( 'success' ),
 		];
 	}
+
+	/**
+	 * Helper method to mock an unauthorized API response.
+	 */
+	public function mock_unauthorized_response() {
+		return [
+			'response' => [
+				'code'    => 401,
+				'message' => 'Unauthorized',
+			],
+			'body'     => json_encode( [ 'error' => 'invalid_api_key' ] ),
+		];
+	}
 }

tests/phpunit/WC_Stripe_Subscription_Renewal_Test.php

@@ -9,6 +9,8 @@
 use WooCommerce\Stripe\Tests\Helpers\WC_Helper_Order;
 use WP_UnitTestCase;
 use MockAction;
+use WC_Stripe_API;
+use WC_Stripe_Database_Cache;
 
 /**
  * These tests assert various things about processing a renewal payment for a WooCommerce Subscription.
@@ -72,6 +74,12 @@ public function set_up() {
 	public function tear_down() {
 		WC_Stripe_Helper::delete_main_stripe_settings();
 
+		// The tests in this file do not mock ALL the calls to the Stripe API, and as we use mocked API keys they trigger the 401 rate-limiter,
+		// this is not a problem for these tests as they don't depend on the reponses.
+		//
+		// TODO: Remove this once we've mocked all calls to the Stripe API (either using the pre_http_request filter, or by using a mocked WC_Stripe_API class).
+		WC_Stripe_Database_Cache::delete( WC_Stripe_API::INVALID_API_KEY_ERROR_COUNT_CACHE_KEY );
+
 		parent::tear_down();
 	}