brin
api

Rate Limiting

brin API rate limits: 60 requests per minute sustained, burst of 10. IP-based, no auth required. Use /bulk for batch lookups.

the API enforces IP-based rate limiting on all endpoints. no auth required — limits are per client IP. one client hitting the limit doesn't affect others.

##limits

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

each IP gets an independent quota. once the burst 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-limitmax 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:

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 this order:

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

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're approaching the limit.
  • honor Retry-After — when you get a 429, wait the indicated seconds before retrying.
  • avoid tight loops — if you need to look up many artifacts sequentially, add a small delay or batch them with /bulk.