Rate limits: every limit and header

To keep the API fast for everyone, LinkHarbor limits the number of requests per minute. The limits do not depend on your plan – there is no monthly quota of API calls. This article lists every limit and shows how your code can handle them cleanly.

#How requests are counted

• Every request falls into exactly one bucket, for example user for authenticated requests or token for the token exchange
• Counting is per full minute (UTC); the counter starts at zero again with every new minute
• Depending on the bucket, the API counts per workspace, per person, per connection or per IP address
• Requests that already fail on the token, scope or schema (401, 403 insufficient_scope, 400, 422 validation_failed from the schema check) do not count; later errors such as 403 feature_not_available do

#All limits

#One budget per workspace

All tokens from API keys in the same workspace share the 600 requests per minute – no matter how many keys you create. The tools of connected AI assistants count here too, because they call the API internally. So more keys do not raise the limit. If a lot of load is spread across several programs, plan around the shared budget.

#The headers

X-RateLimit-Limit

The bucket's limit per minute, for example 600.

X-RateLimit-Remaining

How many requests are left in the current minute.

X-RateLimit-Bucket

The bucket the request fell into, for example user.

Retry-After

Only with 429 rate_limited: seconds until the next minute starts. With api_key_locked, the waiting time is in details.retry_after_sec.

#When the limit is reached

Once the limit is reached, the API responds with HTTP 429 and this body. The text in message is in the account language (see API error format), here in English. Rely on the code rate_limited:

HTTP/1.1 429 Too Many Requests
Retry-After: 37
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Bucket: user

{ "error": "rate_limited", "message": "Too many requests. Please try again in a moment.", "retry_after_sec": 37 }

1. Read Retry-After or retry_after_sec
2. Wait at least that many seconds, plus a little randomness so that not all processes start again at the same moment
3. Retry the request a few times at most
4. If you keep getting 429, spread the work over more time

const BASE = 'https://dock.at-harbor.com';
let cached = null; // { token, expiresAt }

async function getToken() {
  if (cached && Date.now() < cached.expiresAt - 60_000) return cached.token;
  const res = await fetch(BASE + '/v1/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      key_id: process.env.LH_KEY_ID,
      key_secret: process.env.LH_KEY_SECRET,
    }),
  });
  if (!res.ok) throw new Error('Token exchange failed: HTTP ' + res.status);
  const data = await res.json();
  cached = { token: data.token, expiresAt: Date.now() + data.expires_in * 1000 };
  return cached.token;
}

async function lh(method, path, body, attempt = 0) {
  const headers = { Authorization: 'Bearer ' + (await getToken()) };
  if (body !== undefined) headers['Content-Type'] = 'application/json';

  const res = await fetch(BASE + path, {
    method,
    headers,
    body: body === undefined ? undefined : JSON.stringify(body),
  });

  if (res.status === 429 && attempt < 3) {
    const wait = Number(res.headers.get('Retry-After') ?? 5);
    await new Promise((r) => setTimeout(r, (wait + Math.random() * 2) * 1000));
    return lh(method, path, body, attempt + 1);
  }
  if (res.status === 401 && attempt === 0) {
    cached = null; // token expired – try once more with a new token
    return lh(method, path, body, attempt + 1);
  }
  const data = await res.json().catch(() => null);
  if (!res.ok) throw new Error((data && data.error) + ' (HTTP ' + res.status + ')');
  return data;
}

// Example: const { items } = await lh('GET', '/v1/pages');

#Tips for large amounts of data

• Cache the token and only renew it shortly before it expires after 15 minutes
• Watch X-RateLimit-Remaining and slow down when it gets low
• Send requests one after another instead of over dozens of parallel connections
• Load lists once and filter them locally instead of querying each page individually
• Spread large syncs over several minutes
• Retry 5xx errors with increasing pauses, but not 4xx errors

#Other limits

Failed attempts at the token exchange temporarily lock the key and IP, see API keys and tokens. You only send push notifications in the dashboard; their limits are explained in Followers and push notifications.

Your plan's content limits – pages, links, blocks, short links and so on – are not rate limits but fixed caps. They are listed in Plans compared.

#Request size

Every body is measured before the API reads it. How large it may be depends on the endpoint:

If the body is larger, the API responds with 413 request_too_large; details.max_bytes and details.max_kb give the limit. A file that is too large in an upload leads to 413 payload_too_large. Endpoints without a body, such as the DELETE calls, accept no body or only {}.

HTTP/1.1 413 Payload Too Large

{ "error": "request_too_large", "message": "…", "details": { "max_bytes": 65536, "max_kb": 64 }, "request_id": "…" }

There are limits inside the body too: every text has a maximum length, every list a maximum number of entries, and unknown fields are rejected. The values are listed per endpoint in the API reference. A violation leads to 422 validation_failed, and details names the field, rule and limit. The path and query string of a request may be at most 16 KB long together.