Using the API
Rate limits
Limits protect each library and every integration. They apply per credential, per member token, per write scope, per library and per IP address, and higher plans have higher limits. Each library also has a daily quota.
Headers
Every response carries the limits it was checked against (IETF draft-ietf-httpapi-ratelimit-headers), naming the policy closest to its limit:
RateLimit-Policy: "credential";q=240;w=60, "daily";q=20000;w=86400
RateLimit: "credential";r=238;t=42
qis the quota andwthe window in seconds;ris what remains andtthe seconds until it resets.- Slow down before
rreaches 0 rather than waiting for a429.
A request over a limit is 429 rate_limited with Retry-After (seconds); the problem adds limit and window_seconds.
Limits by plan
The per-minute limits depend on the library's plan. A library on a plan not listed here gets the Basic Pro limits.
| Limit | Basic Pro | Silver | Gold | Platinum | Unlimited |
|---|---|---|---|---|---|
| Per credential (API key or OAuth client), requests a minute | 60 | 120 | 240 | 480 | 600 |
| Burst per credential | 20 | 30 | 60 | 100 | 120 |
| Per library, all clients together, requests a minute | 120 | 240 | 480 | 960 | 1,200 |
| Writes a minute, per token or library credential | 10 | 15 | 20 | 30 | 40 |
| Write-scope multiplier | ×1 | ×1 | ×1 | ×2 | ×2 |
| Requests in flight per credential | 3 | 5 | 5 | 10 | 10 |
The write-scope limits are per credential and scope, a minute, at multiplier ×1:
| Scope | At ×1 |
|---|---|
members:create |
30 |
members:update |
60 |
holds:create |
15 |
holds:cancel |
15 |
The multiplier scales both the rate and the burst: on Platinum, holds:create is 30 a minute.
Limits for every plan
| Limit | Value |
|---|---|
| Per member token | 30 requests a minute |
| Before authentication, per IP address (IPv6 per /64) | 300 requests a minute |
| Token endpoint, per IP address | 30 requests a minute |
Libraries may have other values; read the headers rather than hard-coding these.
Daily quota
Each library has a quota of requests a day, counted over all its API keys and OAuth clients together, and a smaller quota of writes (a write counts in both).
| Basic Pro | Silver | Gold | Platinum | Unlimited | |
|---|---|---|---|---|---|
| Requests a day | 5,000 | 10,000 | 20,000 | 40,000 | 60,000 |
| of which writes | 500 | 1,000 | 2,000 | 4,000 | 6,000 |
- The day is the UTC calendar day: the count starts again at 00:00 UTC.
- A request counts when it reaches the operation. A request refused for authentication or by a per-minute limit does not count.
- Over the quota the answer is
429 daily_quota_exceededwithRetry-Afterset to the seconds until the next 00:00 UTC. Retrying earlier cannot succeed. - Responses list the quota in
RateLimit-Policyas"daily"(and, on a write,"daily_writes"), each with a window ofw=86400, andRateLimitnames it when it is the closest limit. - A library's quota can be raised on request; the headers show the quota in force.
To pull the catalogue in bulk, use OAI-PMH, not repeated paging of this API: bulk harvesting spends the daily quota quickly.
Backoff
- On
429, waitRetry-Afterseconds before the next request. - On
503(rate_limit_unavailable,auth_unavailable,search_unavailable) and500, retry with exponential backoff and jitter: for example 1, 2, 4, 8 seconds, each with a random part, capped at about a minute. Retry writes with the sameIdempotency-Key. - Do not retry other
4xxanswers unchanged.
Failed authentication
Repeated failures block the caller for a while:
- Client authentication: 10 failures for one client id within 10 minutes from one network (an IPv4 /24 or IPv6 /64) block that client id from that network for 15 minutes. Other networks are not affected, so one attacker cannot lock your client out everywhere.
- API keys: 20 unknown or invalid keys from one IP address within 10 minutes block it for 15 minutes.
Failures are answered 401, then 429 while blocked. If your deployment rotates secrets, roll out the new secret before the old one stops working.