Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
---
title: "Rate Limiting"
sidebarTitle: "Rate Limiting"
description: "Rate limits and throttling for the Store API"
---
The Store API enforces rate limits to protect against abuse and ensure fair usage. Rate limits are applied per API key or per IP address depending on the endpoint.
## Default Limits
| Endpoint | Limit | Scope | Window |
|----------|-------|-------|--------|
| All endpoints | 300 requests | Per API key | 1 minute |
| `POST /auth/login` | 5 requests | Per IP | 1 minute |
| `POST /customers` | 3 requests | Per IP | 1 minute |
| `POST /auth/refresh` | 10 requests | Per IP | 1 minute |
The global rate limit is tracked by your publishable API key (`X-Spree-Api-Key`). If the key is not provided, the limit falls back to the client's IP address.
Authentication endpoints have stricter per-IP limits to prevent brute-force attacks.
## Rate Limit Headers
Every Store API response includes headers that show your current rate limit usage:
| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Maximum number of requests allowed per window |
| `X-RateLimit-Remaining` | Number of requests remaining in the current window |
| `Retry-After` | Seconds to wait before retrying (only present when limit is reached) |
Example response headers:
```
HTTP/1.1 200 OK
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295
```
## Rate Limit Response
When you exceed the rate limit, the API returns a `429 Too Many Requests` response:
```json
{
"error": {
"code": "rate_limit_exceeded",
"message": "Too many requests. Please retry later."
}
}
```
The response includes rate limit headers and a `Retry-After` header indicating how many seconds to wait before retrying:
```
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
Retry-After: 60
```
## SDK Retry Handling
The Spree SDK automatically handles rate-limited responses with built-in retry logic and exponential backoff:
```typescript
import { createClient } from '@spree/sdk'
const client = createClient({
baseUrl: 'http://localhost:3000',
publishableKey: 'pk_xxx',
retry: {
maxRetries: 2, // Number of retry attempts (default: 2)
baseDelay: 300, // Initial delay in ms (default: 300)
maxDelay: 10000, // Maximum delay in ms (default: 10000)
},
})
```
The SDK respects the `Retry-After` header and only retries on `429` status codes for non-GET requests. For GET/HEAD requests, it also retries on `500`, `502`, `503`, and `504` errors.
## Configuring Rate Limits
If you're self-hosting Spree, you can adjust rate limits in your initializer:
```ruby
# config/initializers/spree.rb
Spree::Api::Config[:rate_limit_per_key] = 300 # Global limit per API key
Spree::Api::Config[:rate_limit_window] = 60 # Window in seconds
Spree::Api::Config[:rate_limit_login] = 5 # Login attempts per IP
Spree::Api::Config[:rate_limit_register] = 3 # Registration attempts per IP
Spree::Api::Config[:rate_limit_refresh] = 10 # Token refresh per IP
Spree::Api::Config[:rate_limit_oauth] = 5 # OAuth callbacks per IP
```
Rate limiting uses `Rails.cache` as the backing store. For production environments with multiple application servers, ensure you're using a shared cache store like Redis:
```ruby
# config/environments/production.rb
config.cache_store = :redis_cache_store, { url: ENV['REDIS_URL'] }
```