The Stax API has network rate limits to safeguard against sudden increases in traffic and fraudulent activity. These network rate limits are in place for both sandbox and production accounts on a per-IP address basis. When hit, they will result in a status of 429. These limits are outlined below. Limits and block times vary by resource.

Rule	Limit	Description	Violation
Global API	200 API requests/min/IP	200 API requests are allowed per minute per IP address across all Stax APIs.	1 Hour
Global API Error	10 API errors/min/IP	10 API failures are allowed per minute per IP address across all Stax APIs(400 errors). This Rule and limit are different from transaction failures.	1 hour
StaxJs	10 StaxJs requests/min/IP	StaxJs limits are much lower than those on the Stax API directly because payment methods are always being tokenized with calls to StaxJs. Only ten requests are allowed per minute.	1 Hour
Terminal APIs	50 requests/min/IP	50 requests are allowed per minute per IP address on all Terminal APIs	1 minute
Ephemeral API (sso)	10 requests/min/IP	The Ephemeral API is used to create temporary authentication keys that represent a merchant’s private API Key. The Ephemeral API also creates SSO tokens for users accessing Stax UIs. Due to the secure nature of this API, the rate limits are much lower than the global rate limit on Stax API	1 Day
StaxJs Transaction Failures	2 failures/10 min/IP	Only two failures/10-minute/IP addresses are allowed when using StaxJs. Since the JS library comes from unique IP addresses of each customer when they are entering their card information, whitelisting IP addresses is not a viable solution due to the nature of the way Javascript works.	1 hour
Strict StaxJs Transaction Failures	1 failure/10 min/IP	When Merchants have previously been identified as a risky merchant or when there has been fraudulent activity in the account’s history with Stax, Stax will prepend`sec_` to the web payments token, which is more strictly used to rate and limit failures on calls to StaxJs.	1 Day

Merchant Rate Limits

Most of Stax’s rate limits are on a per-IP address basis(network rate limits), not a per-merchant basis. For failed transactions, Stax only has a single rate limit on a per-merchant account basis. When a merchant has 50 failed transactions in their account in one hour, their merchant account will be rate-limited and blocked from making additional requests. Unlike Stax's Network rate limits, this merchant rate limit on failures can be modified per merchant basis if there is good reason to increase this limit. Typically, this limit should only be temporarily increased for new accounts processing existing migrated payment methods, during special events, or periods where transaction activity suddenly increases. This increase in activity can often lead to a higher error rate.

Rate Limiting Common Causes

Running a high volume of closely spaced requests, for example, running a monthly job that processes thousands of scheduled transactions without adequate space between requests.
New accounts running migrated payment methods against a charge for the first time. If, for example, some percentage of the migrated payment methods are no longer valid payment methods, there may be a high amount of declines when they are first used.
Increased sale/payment traffic for special events or promotions

Repeat Method Use Rate Limit

PAN (primary account number): By default, the same PAN can only be used for six payments in 12 hours within a specific merchant’s account. This limit can be modified/ increased with approval from Stax’s risk team when there is a valid use case for increasing these limits.

Stax payment method ID: By default, the same payment method ID can only be used once for the same amount during a 5-minute window. This hardcoded rule cannot be overridden on a partner or merchant account basis. This is to protect against duplicate charges if a partner API repeats the same request. To bypass this 5-minute velocity check, you can implement the Stax idempotency feature from the API to indicate that a request is unique.

Prevention and Mitigation

The best way to mitigate against running into rate limits or risk thresholds is to test against the rate limit scenarios above to ensure your software has properly spaced out requests when possible and properly handles errors when those limits are hit before going live.

In many cases, whitelisting IP addresses is the best way to prevent rate limits based on how the software generates requests. If you need to submit a request to whitelist your IP address(es), email the request to [email protected] along with the IP address(es) and, if possible, the user agent.