API rate limits and 429 responses
SnitchFeed API limits per organization: 20 requests a minute per search surface, 60 for org data, 2 in flight at once, plus headers and 429s.
Last updated
Overview
Every v1 endpoint is limited in two ways, per organization (not per key or token):
- Rate: requests per 60-second window, counted separately for each endpoint group below.
- Concurrency: at most 2 in-flight requests at a time across all v1 endpoints combined.
Going over either limit returns 429 Too Many Requests with error code rate_limited, an error.retryAfter value in seconds and a matching Retry-After header.
How requests are counted
Requests pass through authentication, the scope check, the concurrency check and then the rate limiter, in that order.
- A request rejected for authentication, scope or concurrency never reaches the rate limiter and does not use a rate limit token.
- Every request that reaches the rate limiter uses one token, whatever happens next. Validation errors, out-of-credit errors and upstream failures all count.
- Each window lasts 60 seconds from the first request counted in it. When it ends, the full limit is available again.
X-RateLimit-Resettells you when that is. - The concurrency cap counts requests that have started and not yet finished, including slow LinkedIn calls. A third overlapping request is rejected immediately; it does not wait in line. A request releases its slot when its response is sent, whether it succeeded or failed.
/v1/data/* endpoints
20 requests per minute for each search surface. X, LinkedIn and Hacker News each have their own independent counter:
| Surface | Endpoints |
|---|---|
| X | /v1/data/twitter/tweets/search |
/v1/data/linkedin/posts/search, /company/get, /posts/comments, /posts/reactions, /person/posts, /person/comments, /industries | |
| Hacker News | /v1/data/hackernews/search |
A burst of LinkedIn requests does not affect your X or Hacker News allowance. All LinkedIn endpoints, including the free industries lookup, share one counter.
Organization data endpoints
60 requests per minute, one counter shared by:
/v1/mentions(includingPATCH /v1/mentions/{id}/state)/v1/listeners/v1/feeds/v1/organization/context/v1/organization/usage
These endpoints read data already stored for your organization rather than calling an external platform, so they get a higher shared limit.
Response headers
| Header | When present | Meaning |
|---|---|---|
X-RateLimit-Limit | Every response that passed the rate limiter, success or error | Requests allowed per window for the counter this request used (20 for /v1/data/*, 60 otherwise) |
X-RateLimit-Remaining | Same | Requests left in the current window |
X-RateLimit-Reset | Same | Unix timestamp (seconds) when the current window ends |
X-Concurrency-Limit | Every response that passed authentication and the scope check | Max in-flight requests per organization (currently 2) |
X-Concurrency-Remaining | Concurrency 429 only | Always 0 |
Retry-After | Every 429 | Seconds to wait before retrying |
A 429 from the rate limiter does not carry the X-RateLimit-* headers; use Retry-After.
Handling 429s
- Wait for
Retry-Afterseconds before retrying the same request. - Keep at most 2 requests in flight per organization. If several services share one organization, they share this cap.
- Watch
X-RateLimit-Remainingand slow down before it reaches0.
Need higher throughput?
Contact hello@snitchfeed.com if your workload needs custom limits.
Related
- SnitchFeed API: endpoints and error codes
- API credits: what each search call costs
- API authentication: keys and tokens
API scopes and permissions
The six SnitchFeed API scopes, the endpoints each one unlocks, which are on by default for new keys, and how the user's workspace role also limits access.
API credits: cost per endpoint
Credits each SnitchFeed API search endpoint costs, which endpoints are free, what each endpoint returns when you run out of credits, and how to check usage.