Librarika Hubfor developers Test environment
Menu

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
  • q is the quota and w the window in seconds; r is what remains and t the seconds until it resets.
  • Slow down before r reaches 0 rather than waiting for a 429.

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_exceeded with Retry-After set to the seconds until the next 00:00 UTC. Retrying earlier cannot succeed.
  • Responses list the quota in RateLimit-Policy as "daily" (and, on a write, "daily_writes"), each with a window of w=86400, and RateLimit names 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, wait Retry-After seconds before the next request.
  • On 503 (rate_limit_unavailable, auth_unavailable, search_unavailable) and 500, 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 same Idempotency-Key.
  • Do not retry other 4xx answers 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.