brin
api

Rate Limiting

How the brin API enforces request rate limits per client IP

The API enforces IP-based rate limiting on all endpoints. No authentication is required, so rate limits are applied per client IP address — one client hitting the limit does not affect others.

##Limits

ParameterValue
Sustained rate60 requests per minute (1 req/s)
Burst allowance10 requests (sent instantly)
Replenish rate1 token per second

Each IP address gets an independent quota. Once the burst allowance is exhausted, requests are throttled to 1 per second until tokens replenish.

The /bulk endpoint counts as a single request regardless of how many lookups it contains (up to 100). Use it to stay well within limits when checking multiple artifacts.

##Response headers

Every API response includes rate limit headers so clients can track their quota:

Text
x-ratelimit-limit:      60
x-ratelimit-remaining:  58
x-ratelimit-after:      0
HeaderDescription
x-ratelimit-limitMaximum requests allowed per minute
x-ratelimit-remainingRequests remaining in the current window
x-ratelimit-afterSeconds until the next request is allowed (0 when not throttled)

##Rate-limited responses

When the limit is exceeded, the API returns HTTP 429 Too Many Requests:

JSON
{
  "error": "rate_limit_exceeded"
}

The response includes a Retry-After header indicating how many seconds to wait before retrying.

Text
HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json
 
{ "error": "rate_limit_exceeded" }

##Client IP detection

Behind reverse proxies, the client IP is extracted in the following order:

  1. X-Forwarded-For header
  2. X-Real-IP header
  3. TCP peer address (fallback)

This means requests routed through load balancers and CDNs are correctly attributed to the originating client.

##Best practices

  • Use /bulk for batch lookups — a single bulk request with up to 100 items counts as one request against your quota.
  • Read the response headers — check x-ratelimit-remaining to know when you are approaching the limit.
  • Honor Retry-After — when you receive a 429, wait the indicated number of seconds before retrying.
  • Avoid tight loops — if you need to look up many artifacts sequentially, add a small delay between requests or batch them with /bulk.