Rate Limiting
Explore our guide on API rate limiting to prevent misuse and ensure efficient operation. Dive into classifications, enforcement, and management across our product suite's API categories.
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.
The rate limit category for an API call is documented in the description of the operation.
API rate limit action categories are as follows:
| Routing Ratelimit Categories | Description |
|---|---|
| Payment Transaction Authorization | Operations needed to authorize a payment transaction as part of the purchase flow. |
| Payment Request Management | Operations used to read, update or cancel a payment request or payment token. |
| Payment Request Headless Management | Operations needed for managing payment requests in a headless interaction flow. |
| Payment Presentation | Operations needed for presenting Klarna as a payment method across the checkout. |
| Payment Pre-Qualification | Operations used to pre-qualify a customer before a purchase. |
| Payment Dispute Management | Operations related to handling of payment disputes. |
| Payment Transaction Management | Operations needed to manage a payment, and some optional operations for a payment capture. |
| Customer Post Purchase | Operations focused on functionality for post-purchase for end-users. |
| Identity Request Authorization | Operations needed to authorize a customer identity request as part of the purchase flow. |
| Identity Request Management | Operations used to read, update or cancel an identity request. |
| Identity Request Headless Management | Operations needed for managing identity requests in a headless interaction flow. |
| Customer Token Management | Operations used to introspect or revoke customer tokens issued in the account linking flow. |
| Card Settlement Authorization | Operations needed to authorize a card settlement as part of the purchase flow. |
| Card Settlement Management | Operations used to manage card settlements. |
| Partner Account Onboarding | Operations necessary to onboard or migrate a partner account and provision its initial resources. |
| Partner Account Management | Operations used to manage a partner account and its resources, after onboarding. |
| Plugin Management | Operations used by plugins to authenticate and fetch available features. |
| Network Session Token | Operations needed to generate Klarna network session tokens for initializing Klarna integrations. |
| Identifier Resolution | Operations used to resolve access policy, partner account and payment account identifiers. |
| Settlements Processing | Operations needed for processing of settlements. |
Workload classification
We classify API traffic into workload types to help prevent background processing from interfering with real-time payment flows. An optional request header routes background traffic to a dedicated rate limit bucket, separate from the interactive quota described in the tables below.
Klarna-Workload-Type header
To classify a request as background traffic, include the following header:
JSON
1
Klarna-Workload-Type: backgroundRequests that include this header with the value
background (case-insensitive) are metered against a separate background rate limit bucket.To explicitly indicate interactive traffic, you can set the header to
standard:JSON
1
Klarna-Workload-Type: standardRequests with
standard or without the header are treated as interactive traffic and metered against the standard rate limits documented in the tables below.Unsupported header values are rejected with HTTP status
400 Bad Request.Background rate limits
Background rate limits are a percentage of the corresponding interactive rate limit for each API category. The exact background quota is included in the rate limit response headers when the header is used.
Background quotas are best-effort. When the platform is under heavy load, Klarna may temporarily reduce background limits to preserve capacity for interactive traffic.
| Behavior | Interactive (default) | Background |
|---|---|---|
| Header value | Omitted or standard | background |
| Rate limit bucket | Standard quota (see tables below) | Separate, dedicated quota |
| Isolation | N/A | Background traffic cannot consume interactive quota |
| Invalid header value | Rejected with 400 Bad Request | Rejected with 400 Bad Request |
When to use background classification
The
Klarna-Workload-Type: background header is intended for scheduled or bulk processing jobs, such as:- Background settlement report retrieval
- Periodic account reconciliation
This header should not be used for real-time or revenue-generating requests — for example checkout, customer-initiated payment capture, or token charges (on-demand or subscription charges against a stored token). Token charges can resemble scheduled batch jobs, but they are time-sensitive purchases: metering them against the reduced background quota risks throttling that delays or loses sales.
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:
| Rate Limit by API Category in Production | Partner | Acquiring Partner |
|---|---|---|
| payment-authorization | 50/s | 100/s |
| payment-request-management | 50/s | 100/s |
| payment-request-headless-management | 150/s | 300/s |
| payment-presentation | 200/s | 500/s |
| payment-pre-qualification | 100/s | 200/s |
| payment-dispute-management | 20/s | 50/s |
| payment-transaction-management | 200/s | 300/s |
| customer-transaction-management | 80/s | 80/s |
| identity-authorization | 50/s | 100/s |
| identity-request-management | 10/s | 20/s |
| identity-request-headless-management | 150/s | 300/s |
| identity-token-management | 10/s | 20/s |
| card-settlement-authorization | 10/s | 10/s |
| card-settlement-management | 10/s | 10/s |
| partner-account-onboarding | 10/s | 10/s |
| partner-account-management | 10/s | 20/s |
| plugins-management | 10/s | 20/s |
| interoperability | 40/s | 80/s |
| identifier-resolution | 10/s | 20/s |
| settlement | 20/s | 30/s |
| Rate Limit by API Category in Test | Partner | Acquiring Partner |
|---|---|---|
| payment-authorization | 15/s | 25/s |
| payment-request-management | 15/s | 25/s |
| payment-request-headless-management | 40/s | 75/s |
| payment-presentation | 50/s | 125/s |
| payment-pre-qualification | 25/s | 50/s |
| payment-dispute-management | 5/s | 15/s |
| payment-transaction-management | 50/s | 125/s |
| customer-transaction-management | 20/s | 20/s |
| identity-authorization | 15/s | 25/s |
| identity-request-management | 5/s | 5/s |
| identity-request-headless-management | 40/s | 75/s |
| identity-token-management | 5/s | 5/s |
| card-settlement-authorization | 5/s | 5/s |
| card-settlement-management | 5/s | 5/s |
| partner-account-onboarding | 5/s | 5/s |
| partner-account-management | 5/s | 5/s |
| plugins-management | 5/s | 5/s |
| interoperability | 10/s | 20/s |
| identifier-resolution | 5/s | 5/s |
| settlement | 5/s | 20/s |
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:
JAVASCRIPT
1
2
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 (values approximate, provided on a best-effort basis):
JSON
1
2
3
4
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.
Background workload example
When the
Klarna-Workload-Type: background header is sent, the rate limit response headers reflect the background-specific quota. Background rate limit names are prefixed with background_ to distinguish them from interactive limits:JSON
1
2
3
X-Ratelimit-Limit: 6, 6;w=1;name="background_account_settlement",45;w=1;name="background_psp_settlement"
X-Ratelimit-Remaining: 4
X-Ratelimit-Reset: 1The information returned with the above response should be interpreted as follows:
- The background quota closest to being reached for the interval is 6 requests per second with the descriptive name "background_account_settlement".
- The
background_prefix indicates these limits apply to background-classified traffic only. - Interactive traffic for the same Partner and category is tracked separately and is unaffected by the background quota consumption.
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.
- Background job interference: Large background processing jobs running without the
Klarna-Workload-Type: backgroundheader may consume the interactive rate limit quota, potentially affecting real-time payment flows. To mitigate this, we recommend classifying background traffic using the header. This routes background requests to a dedicated rate limit bucket and preserves the interactive quota for customer-facing actions.
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.
Testing
Live Environment
Running any performance tests in the live environment is not allowed. This prohibition covers scenarios such as load tests, stress tests, and other evaluations that might negatively impact live operations.
Test Environment
In the test environment, you may run limited performance tests to confirm that your merchant integration behaves as expected when a rate limit is reached. Note that the deliberately lower rate limits in this environment are designed to trigger such events more easily. These tests are only intended for verifying integration behavior and should not be used for capacity testing.