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
}
{
"error": "rate_limited",
"error_description": "Too many token requests. Try again later."
}
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.
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.
