Rate limits

Limit per key

Each API key has its own budget of requests per minute. The default is 120 requests per minute. The shop operator can set a different value for your access, between 1 and 10,000.

The budget belongs to the key, not to your IP address. Two apps behind the same IP address, for example on the same cloud platform, do not use up each other’s budget.

Headers

Responses carry the current state of your budget:

Header	Meaning
X-RateLimit-Limit	Requests allowed per minute for your key
X-RateLimit-Remaining	Requests left in the current minute

When the budget is used up, the API answers 429 and adds:

Header	Meaning
Retry-After	Seconds until you can send again
X-RateLimit-Reset	Time when the budget resets, as a Unix timestamp

HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
Content-Type: application/json

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests.",
    "details": []
  }
}

Failed authentication attempts

Requests with a wrong key are limited separately, so that keys cannot be guessed:

• at most 60 failed attempts per minute for the same key prefix from the same IP address
• at most 300 failed attempts per minute from the same IP address across all prefixes

A request without a key, or with a key that does not match the key format, does not count. A successful request with the correct key resets the counter for its prefix.

When this limit is reached, the API also answers 429 rate_limited with Retry-After, with the message Too many authentication attempts. If you see this message, your app is sending a wrong or outdated key. Check the key before retrying; repeating the same request will not help.

Handling 429

• Wait at least the number of seconds in Retry-After, then send the same request again.
• Do not retry immediately in a loop. Each rejected request still costs the shop processing time.
• If you reach the limit regularly, spread your requests over time or ask the operator for a higher limit.
• Use X-RateLimit-Remaining to slow down before you reach the limit, for example during bulk updates.

Retrying an order after 429 is safe. See Retries and duplicate protection.