Limity zapytań: wszystkie limity i nagłówki

Aby API działało szybko dla wszystkich, LinkHarbor ogranicza liczbę żądań na minutę. Limity nie zależą od Twojego planu – nie ma miesięcznego limitu wywołań API. Ten artykuł wymienia wszystkie limity i pokazuje, jak Twój kod może je poprawnie obsłużyć.

#Jak liczone są żądania

• Każde żądanie trafia do dokładnie jednego koszyka, na przykład user dla uwierzytelnionych żądań lub token dla wymiany tokenu
• Liczenie odbywa się w pełnych minutach (UTC); z każdą nową minutą licznik zaczyna od zera
• W zależności od koszyka API liczy na workspace, na osobę, na połączenie lub na adres IP
• Żądania, które nie przechodzą już na etapie tokenu, zakresu lub schematu (401, 403 insufficient_scope, 400, 422 validation_failed z kontroli schematu), nie są liczone; późniejsze błędy, takie jak 403 feature_not_available, są liczone

#Wszystkie limity

#Jeden budżet na workspace

Wszystkie tokeny z kluczy API w tym samym workspace dzielą 600 żądań na minutę – bez względu na to, ile kluczy utworzysz. Wliczają się tu też narzędzia połączonych asystentów AI, bo wewnętrznie wywołują API. Więcej kluczy nie podnosi więc limitu. Jeśli duże obciążenie rozkłada się na kilka programów, planuj z uwzględnieniem wspólnego budżetu.

#Nagłówki

X-RateLimit-Limit

Limit koszyka na minutę, na przykład 600.

X-RateLimit-Remaining

Ile żądań zostało w bieżącej minucie.

X-RateLimit-Bucket

Koszyk, do którego trafiło żądanie, na przykład user.

Retry-After

Tylko przy 429 rate_limited: liczba sekund do początku następnej minuty. Przy api_key_locked czas oczekiwania znajduje się w details.retry_after_sec.

#Gdy limit zostanie osiągnięty

Po osiągnięciu limitu API odpowiada kodem HTTP 429 i taką treścią. Tekst w message jest w języku konta (zobacz Format błędów API), tutaj po angielsku. Polegaj na kodzie 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. Odczytaj Retry-After lub retry_after_sec
2. Odczekaj co najmniej tyle sekund, plus trochę losowego czasu, aby nie wszystkie procesy ruszyły ponownie w tym samym momencie
3. Ponów żądanie najwyżej kilka razy
4. Jeśli nadal dostajesz 429, rozłóż pracę na dłuższy czas

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 wygasł – spróbuj jeszcze raz z nowym tokenem
    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;
}

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

#Wskazówki przy dużych ilościach danych

• Przechowuj token w pamięci podręcznej i odnawiaj go dopiero tuż przed wygaśnięciem po 15 minutach
• Obserwuj X-RateLimit-Remaining i zwolnij, gdy wartość robi się niska
• Wysyłaj żądania jedno po drugim zamiast przez dziesiątki równoległych połączeń
• Wczytuj listy raz i filtruj je lokalnie, zamiast odpytywać każdą stronę osobno
• Rozkładaj duże synchronizacje na kilka minut
• Ponawiaj błędy 5xx z rosnącymi przerwami, ale nie błędy 4xx

#Inne limity

Nieudane próby wymiany tokenu tymczasowo blokują klucz i IP, zobacz Klucze API i tokeny dostępu. Powiadomienia push wysyłasz tylko w panelu; ich limity wyjaśnia artykuł Obserwujący i powiadomienia push.

Limity treści Twojego planu – strony, linki, bloki, krótkie linki itd. – nie są limitami zapytań, lecz stałymi górnymi granicami. Znajdziesz je w artykule Porównanie planów.

#Rozmiar żądania

Każda treść żądania jest mierzona, zanim API ją odczyta. Jak duża może być, zależy od endpointu:

Jeśli treść jest większa, API odpowiada kodem 413 request_too_large; details.max_bytes i details.max_kb podają limit. Zbyt duży plik przy przesyłaniu prowadzi do 413 payload_too_large. Endpointy bez treści, takie jak wywołania DELETE, nie przyjmują treści albo przyjmują tylko {}.

HTTP/1.1 413 Payload Too Large

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

Limity obowiązują też wewnątrz treści: każdy tekst ma maksymalną długość, każda lista maksymalną liczbę wpisów, a nieznane pola są odrzucane. Wartości dla każdego endpointu znajdziesz w dokumentacji API. Naruszenie prowadzi do 422 validation_failed, a details podaje pole, regułę i limit. Ścieżka i query string żądania mogą mieć razem najwyżej 16 KB.