Bkmark API Rate Limits, Quotas, and Throttling Policies

Bkmark enforces rate limits to ensure consistent performance for all users. Limits vary by endpoint and are keyed either to your client_id (for OAuth2 endpoints) or to the authenticated userId (for resource endpoints). When you exceed a limit, the API returns a 429 Too Many Requests response. Understanding these limits upfront helps you design integrations that stay within bounds and degrade gracefully when they don’t.

OAuth2 Endpoint Limits

These limits apply to the OAuth2 authentication endpoints. They are keyed by client_id unless noted otherwise.

Endpoint	Limit	Key	Description
`POST /oauth/token`	60 / minute	`client_id`	Token exchange (authorization code) and token refresh
`POST /oauth/authorize`	20 / minute	`userId`	Authorization consent processing
`POST /oauth/revoke`	30 / minute	`client_id`	Token revocation

API Endpoint Limits

These limits apply to resource and action endpoints. They are keyed by the authenticated userId.

Endpoint	Limit	Key	Description
`POST /bookmarks/import`	5 / hour	`userId`	Bulk bookmark imports
`POST /bookmarks/import/pocket`	5 / hour	`userId`	Pocket bookmark imports
`POST /bookmarks/import/raindrop`	5 / hour	`userId`	Raindrop bookmark imports
`POST /bookmarks/:id/summarize`	10 / day	`userId`	AI-powered bookmark summarization

Rate Limit Response

When you exceed a rate limit, the API responds with 429 Too Many Requests and the following JSON body:

{
  "error": "rate_limited",
  "message": "Too many requests. Try again later.",
  "statusCode": 429
}

OAuth2 endpoints follow RFC 6749 and return a slightly different error format:

{
  "error": "rate_limited",
  "error_description": "Too many token requests. Try again later."
}

In both cases, use the error field to detect rate limiting programmatically and distinguish it from other 4xx errors.

Best Practices

Following these practices will keep your integration well within rate limits for the vast majority of use cases.

Cache responses wherever possible. If your integration frequently reads the same bookmark list or tag data, store the response locally and revalidate only when you know the data has changed. This is especially effective for data that updates infrequently, such as tag lists or group membership. Use webhooks instead of polling. Rather than repeatedly calling GET /bookmarks to check for new items, subscribe to webhook events. Bkmark will push a notification to your endpoint the moment a relevant change occurs, eliminating polling overhead entirely. Batch operations with /bookmarks/bulk. If you need to create, update, or delete multiple bookmarks, use the POST /bookmarks/bulk endpoint rather than making individual requests in a loop. A single bulk call counts as one request against your rate limit regardless of how many bookmarks it touches. Implement exponential backoff on 429 responses. When you receive a 429, wait before retrying. Start with a short delay (for example, 1 second), then double the delay on each successive 429 up to a maximum (for example, 60 seconds). Adding a small random jitter helps prevent multiple clients from retrying in lockstep.

# Pseudocode: exponential backoff with jitter
delay = 1  # seconds
max_delay = 60

while True:
    response = call_api()
    if response.status != 429:
        break
    sleep(delay + random(0, 1))
    delay = min(delay * 2, max_delay)

If you are consistently hitting rate limits in production, review whether you can reduce API call frequency with caching or batching. For higher limits, contact the Bkmark team to discuss your integration’s needs.

Overview

Endpoints

OAuth2

Bkmark API Rate Limits, Quotas, and Throttling Policies

OAuth2 Endpoint Limits

API Endpoint Limits

Rate Limit Response

Best Practices

​OAuth2 Endpoint Limits

​API Endpoint Limits

​Rate Limit Response

​Best Practices

OAuth2 Endpoint Limits

API Endpoint Limits

Rate Limit Response

Best Practices