Rate limit

Klarna uses a number of measures to ensure stable operations for Klarna services, one of which is API rate limiting. If you send too many requests in a short amount of time, your requests may be subject to rate limiting.

A rate-limited request will return both:

  • a client error using HTTP-status code 429
  • HTTP headers containing information about the current limit and when the API quota is set

Each request will also return a header value indicating the remaining quota with every response.

Rate limits are measured per merchant_id, not per API credential. Rate limiting is measured on a per-operation basis and categorizes operations as either “create-session” or other operations. If a merchant_id has entered rate limiting, all subsequent requests will be returned with a rate limit status code until the rate limit resets.

Live (production) environments: the API rate limit is 40 create-sessions per second. For the other operations, the API limit is 200 requests per second.

Testing (playground) environments: the API rate limit is 5 requests per second for create-sessions and 50 requests per second for other operations.

If you are frequently experiencing rate limitations, contact Merchant Support (https://www.klarna.com/merchant-support/) for advice on how to remedy the situation.

We may change rate limits to prevent abuse or address poorly behaving integrations.

Rate limit Information

The following headers are used to indicate the status of the rate-limiting:

  • X-Ratelimit-Limit - Information on the rate limit and the metering interval
  • X-Ratelimit-Reset - How many seconds remain until the current metering interval resets
  • X-Ratelimit-Remaining - The approximate remaining quota of the rate limit

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

Example:

Copy
Copied
X-Ratelimit-Limit: 40, 40;w=1
X-Ratelimit-Remaining: 15
X-Ratelimit-Reset: 1

The information returned with the above response should be interpreted as follows:

  • The rate limit quota for the interval is 40 requests for this operation
  • 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

Handling Rate limiting gracefully

If you receive HTTP status code 429, we recommend that you use a retry mechanism with exponential back-off. We also highly recommend adding some jitter to the back-off to prevent retry requests from being retried all at the same time (which may trigger further rate limiting).

To further reduce any rate limiting, we also suggest that you use a token bucket algorithm to control the global flow of requests from the calling system to the API.

Common causes, mitigation, and support

We try to set the rate limiting quotas such that the vast majority of merchants are never rate limited for legitimate traffic. However, you might still encounter a rate limit in the following situations:

  • A high rate of requests within a short time period can trigger rate limiting. In order to mitigate this, we recommend that you pace your requests over the full interval indicated by the informational headers, and do retries with exponential backoff.
  • A sudden, large increase in traffic (for example, as a result of a flash sale) can exhaust the rate limit quota. If you anticipate that an upcoming event will exceed your request quota, please contact Merchant Support ( https://www.klarna.com/merchant-support/ ) for assistance.
  • Bot activity on a site can generate high rate of requests that can trigger rate limiting. It's recommended to adopt bot-detection techniques and in case of suspected bots to trigger user authentication before calling APIs.