Rate Limits

The API enforces rate limits at two levels to protect service quality.

Per-Plan Limits

Rate limits are based on your subscription plan:

Plan	Requests/min	Requests/day
Pro	120	10,000

API access requires a paid plan (Pro). Free plan users cannot create API tokens.

Heavy Endpoint Limits

Some resource-intensive endpoints have a stricter limit of 2 requests per minute:

POST /import -- importing bookmarks (matches any path starting with /import)
POST /export -- exporting your library (matches any path starting with /export)
DELETE /bookmarks/trash -- emptying trash
GET /bookmarks/duplicates -- finding duplicate bookmarks
GET /smart-folders/:id/bookmarks -- evaluating smart folder rules

Rate Limit Headers

Every API response includes rate limit information:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1712234567

Header	Description
`X-RateLimit-Limit`	Your plan's per-minute limit
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp (seconds) when the window resets

These headers always come from the API itself and describe your plan quota. The gateway's IP shield (below) never rewrites or emits them; its own 429 / 403 responses carry only Retry-After.

Rate Limit Exceeded

When you exceed the limit, you'll receive a 429 response:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded"
  },
  "meta": { "requestId": "req_a1b2c3d4e5f6a1b2" }
}

Best practice: check X-RateLimit-Remaining and back off before hitting 0. When you receive a 429, wait until the X-RateLimit-Reset timestamp before retrying.

IP-Based Protection

Requests are also subject to IP-level protection:

The API gateway allows 60 requests per minute per IP address.
Failed authentication attempts have an additional token bucket that refills at 30 requests per minute, with a burst capacity of 10. Valid-token traffic does not use this bucket.
5 failed auth attempts in 5 minutes triggers a 15-minute IP block (403).
Gateway-level 429 and 403 responses include a Retry-After header (seconds) and no X-RateLimit-* headers — those counters are per-edge-isolate and are not an authoritative quota.

IP blocking returns:

{
  "error": "IP temporarily blocked due to repeated authentication failures",
  "meta": { "requestId": "req_..." }
}