Rate limiting

To safeguard our APIs from potential misuse due to coding errors, suboptimal integrations, and malicious activities, we implement proactive rate limiting. This document outlines the classifications, enforcement, and management of rate limits across various API categories critical to our product suite.

API operation categories

We classify API actions based on their relevance to the purchase process and the resources they consume. This classification helps minimize interference between processes, ensuring efficient operation. For example, we strive to prevent extensive settlement report processes from impacting new payment transaction capabilities.

API rate limit action categories are as follows:

• Account onboarding: involves resource-intensive tasks such as creating accounts, requiring synchronous calls to other APIs.
• Payment transaction capture: crucial actions for capturing payment transactions.
• Payment transaction management: covers actions related to managing payment transactions that are not essential for the capture process.
• Settlement: includes actions that could affect rate limits in other areas, identified through access log analysis.
• Dispute: specifically addresses operations related to handling disputes.
• Partner management: encompasses workflows for managing partners, excluding the onboarding of new partner accounts.

Rate limit enforcement

Requests to the global API endpoint are processed in the closest data center relative to the caller's location. The rate limit configuration for a given Partner and Acquiring partner is the same across all locations within a specific environment. However, the rate limit quota is enforced by each data center. Therefore, requests for the same Partner from different parts of the world may experience different rate limit statuses.

The rate limit mechanism tracks rate limits for API operations at two distinct levels:

• Acquiring partner level: This encompasses all operations, including those on sub-partners.
• Partner level: These limits apply uniquely to each Partner. If either limit is reached, a request will be subject to rate limiting:

Handling rate limits

A rate-limited request returns an HTTP-status code 429 and headers indicating the remaining quota:

• X-Ratelimit-Limit : information on the rate limits and the metering interval. The first item is the quota that is closest to being exceeded. This is followed by one or more rate limit quota policy descriptions.
• X-Ratelimit-Reset : time in seconds until the current metering interval resets.. For per-second rate limiting, this will always be “1”.
• X-Ratelimit-Remaining : the approximate remaining quota of the rate limit When a rate limit is reached, we require implementing a retry mechanism with exponential back-off to prevent retry attempts from retriggering rate limiting; add jitter to the back-off as retrying all attempts together is likely to draw out the issue. In addition, Klarna suggests that a token bucket algorithm is used to control the global flow of requests from the calling system to the API, this will help to reduce the likelihood of rate limiting in future.

Rate limit quota policy

A rate limit quota policy element is describing a rate limit that has been evaluated for the request. More than one can be active at the same time. In the current API there will be two, one for the Acquiring Partner-level rate limit and one for the Partner rate limit. Example of a single quota policy:

40;w=1;name="ratelimit-name"

• The “40” is how many units are available within a refresh-interval.
• The “w=1” describes the length in seconds of interval after which the rate limit quota is reset.
• The “name” component is optional and should be seen as informational and can change without notice. Typical values for the name will include the level where the rate limit applies and the rate limit operation category.

Example: The values in the headers are approximate and provided on a best-effort basis.

X-Ratelimit-Limit: 40, 40;w=1;name="account_payment-request-capture",100;w=1;name="psp_payment-request-capture"
X-Ratelimit-Remaining: 15
X-Ratelimit-Reset: 1

• The rate limit quota closest to being reached for the interval is 40 requests per second with the descriptive name “account_payment-request-capture”.
• The quota window interval is 1 second.
• There are 15 requests remaining within the 1-second time window before further requests are rejected.
• There is 1 second until this quota resets.

Common causes for rate limiting

We aim to set rate limiting quotas to ensure that the majority of partners experience no rate limitations for legitimate traffic. However, you may encounter rate limits in the following scenarios:

• High request rate : Exceeding the defined rate limits due to a rapid influx of requests within a short timeframe may trigger rate limiting. To address this, it is advised to distribute requests evenly over the interval specified by informational headers and employ retries with exponential backoff.
• Traffic surges : A sudden and substantial increase in traffic, such as during a flash sale, can deplete the rate limit quota. If you anticipate an upcoming event that may surpass your request quota, kindly reach out to Partner Support or contact your Account Manager for assistance.
• Bot-generated requests : The presence of bots on a website may result in an increased frequency of requests, potentially leading to rate limiting as a preventive measure against web scraping or data harvesting. It is recommended to implement bot-detection methods and, if suspicious bot activity is detected, initiate authentication before making API calls.

Rate limiting change management

Adjustments to rate limiting protocols are managed per the Klarna change management process as outlined in Versioning and deprecation. Changes may occur without prior notice in response to abuse or consistent deviation from Klarna’s requirements.

It is crucial to monitor the rate limiting information returned in response headers to adapt to any adjustments effectively.