Documentation
Rate Limits
Understand SOCWarden's rate limiting model, per-plan quotas, and how to handle 429 responses.
Per-plan rate limits
Rate limits are enforced per API key using a sliding window. Exceeding the limit returns 429 Too Many Requests.
| Plan | RPM | Events/sec | Batch limit | Monthly cap |
|---|---|---|---|---|
| Free | 30 | 5 | Not available | 2,500 events |
| Starter | 500 | 25 | 50 events/batch | 25,000 events* |
| Pro | 1,000 | 100 | 100 events/batch | 100,000 events* |
| Business | 2,000 | 1,000 | 100 events/batch | 500,000 events* |
* Paid plans use overage billing beyond the included quota. Free plan drops events after the cap.
Per-IP hard cap
In addition to per-key limits, SOCWarden enforces a hard cap of 600 requests per minute per source IP. This protects against abuse even if multiple API keys are used from the same origin.
This limit is not configurable. If you operate multiple tenants behind a shared egress IP (e.g., a NAT gateway), contact support to have the cap raised.
Response headers
Every response from POST /v1/events includes rate limit headers:
| Header | Description |
|---|---|
| X-RateLimit-Limit | Maximum requests allowed in the current window |
| X-RateLimit-Remaining | Requests remaining in the current window |
| X-RateLimit-Reset | Unix timestamp when the window resets |
| Retry-After | Seconds to wait before retrying (only present on 429) |
Example successful response headers:
HTTP/1.1 202 Accepted X-RateLimit-Limit: 500 X-RateLimit-Remaining: 487 X-RateLimit-Reset: 1711234560
429 response body
When rate limited, the ingestor returns a JSON error body:
HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1711234560
Content-Type: application/json
{
"error": "RATE_LIMITED",
"message": "Rate limit exceeded. Retry after 60 seconds.",
"retry_after": 60
}SDK auto-backoff behavior
All official SOCWarden SDKs (Laravel, Node.js, Python, Go, Browser) implement automatic backoff when a 429 is received:
- Immediate cooldown: On first 429, the SDK enters a 1-hour cooldown period and stops sending events.
- Probe retries: Every 5 minutes during cooldown, the SDK sends a single probe request to check if the rate limit has reset.
- Auto-resume: On a successful probe (non-429), the SDK resumes normal event delivery immediately.
- Silent drop: Events generated during the cooldown period are silently dropped. They are not queued or buffered.
Agent behavior
The SOCWarden Agent handles rate limits differently: it buffers events in a local database and retries with exponential backoff. No events are lost during rate limiting when using the agent.
Free plan monthly cap
Free plan accounts are limited to 2,500 events per calendar month. After reaching this cap:
- New events are silently dropped (the ingestor still returns 202 but discards the payload)
- Existing events and enrichment data remain accessible in the dashboard
- The counter resets on the 1st of each month at 00:00 UTC
- Dashboard → Usage shows your current event count and remaining quota
To avoid drops, upgrade to a paid plan. Starter ($12/mo) includes 25,000 events with overage billing at $0.002/event instead of hard drops.
Batch endpoint limits
The batch endpoint POST /v1/events/batch allows sending multiple events in a single request. Batch limits vary by plan:
| Plan | Max events per batch | Notes |
|---|---|---|
| Free | Not available | Batch endpoint returns 403 |
| Starter | 50 | Each event in the batch counts toward RPM and monthly quota |
| Pro | 100 | Each event in the batch counts toward RPM and monthly quota |
| Business | 100 | Each event in the batch counts toward RPM and monthly quota |
Batches exceeding the limit are rejected entirely with 400 BATCH_TOO_LARGE. Partial acceptance is not supported.