Limity częstotliwości API

Elido nakłada limity częstotliwości API na klucz, a nie na obszar roboczy. Oznacza to, że każda zbudowana przez Ciebie integracja może wysycić własny limit bez ograniczania pozostałych. Ten artykuł opisuje limity dla poszczególnych planów, nagłówki, które należy odczytywać, oraz sposób na bezpieczne zmniejszenie częstotliwości żądań.

Liczby

Stałe limity na klucz:

Plan	Na minutę	Burst
Free	60	120
Pro	600	1200
Business	6000	12000

Burst to wartość, którą możesz krótko przekroczyć w 10-sekundowym oknie. Limit stały (sustained) to stały pułap, z jakim uzupełniana jest pula żądań.

Nie ma limitów dla poszczególnych punktów końcowych — GET /v1/links liczy się tak samo jak POST /v1/links. Jedyne wyjątki to:

• POST /v1/bulk-import — maksymalnie 5 aktywnych importów jednocześnie na obszar roboczy.
• POST /v1/links z własnym slugiem kolidującym z istniejącym — te żądania wciąż są wliczane, ale w przypadku konfliktu slot nie jest zwracany.
• GET /v1/analytics/timeseries z interval=second — limit wynosi 60/minutę nawet w planie Business, ponieważ bazowe zapytanie ClickHouse jest bardziej obciążające.

Nagłówki odpowiedzi

Każda odpowiedź API zawiera:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587
X-RateLimit-Reset: 1747386240

X-RateLimit-Reset to znacznik czasu Unix informujący, kiedy pula zostanie całkowicie uzupełniona. Używaj go do planowania ponownych prób zamiast stosowania stałych opóźnień.

Jak wygląda błąd 429

Po przekroczeniu limitu:

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "error": "rate_limited",
  "message": "API rate limit exceeded for this key",
  "retry_after_seconds": 12
}

Retry-After jest podany w sekundach. Odczekaj wskazany czas, a następnie ponów próbę. SDK robią to automatycznie z wykorzystaniem jittera; jeśli piszesz własny klient HTTP, postępuj tak samo.

Strategia wycofywania (backoff)

Jeśli intensywnie korzystasz z API (jednorazowe zadanie masowe, uzupełnianie danych), dostosuj tempo klienta do limitu stałego, a nie do limitu burst. Zwykła pętla szybko osiągnie limit burst, zatrzyma się na 50 sekund, a potem znów uderzy w limit burst — co daje średnią gorszą niż przy miarowym wysyłaniu żądań.

Pseudokod:

const limit = 600; // na minutę
const delayMs = (60 * 1000) / limit; // 100ms między żądaniami

for (const item of items) {
  await fetch(...);
  await sleep(delayMs);
}

Ten wzorzec wykorzystuje 100% limitu przy zerowej liczbie błędów 429.

Współbieżność

Współbieżne żądania współdzielą pulę. Jeśli wyślesz 100 równoległych żądań z puli workerów w planie Pro (600/min), pierwsze 100 powidzie się natychmiast; pula będzie się następnie uzupełniać w tempie 10/sek. Twoja pula workerów powinna celować w stały poziom przepustowości, a nie w głębokość kolejki.

Na klucz vs na IP

Pula jest przypisana do klucza, a nie do adresu IP. Jeśli używasz tego samego klucza na 10 maszynach, te 10 maszyn współdzieli limit. Wygeneruj osobny klucz dla każdej maszyny, jeśli potrzebujesz 10-krotnie większego zapasu.

Warstwa IP ma oddzielny, bardzo hojny limit (10 000/min/IP), który ma na celu jedynie powstrzymanie wadliwie działających klientów. Przy normalnym użytkowaniu nigdy go nie osiągniesz; jeśli jednak tak się stanie, otrzymasz odpowiedź 429 z treścią "error": "ip_rate_limited".

Klucze idempotencji nie omijają limitów

Wielokrotne wysyłanie tego samego Idempotency-Key nadal obciąża Twoją pulę żądań — możemy zwrócić zapisaną w pamięci podręcznej odpowiedź bez wykonywania pracy u podstaw, ale licznik zostanie zwiększony. Nie zapętlaj żądań z kluczami idempotencji jako strategii ponawiania prób.

Zwiększanie limitów

Jeśli Twój przypadek użycia naprawdę wymaga więcej niż 6000/min stałej przepustowości, wyślij e-mail na adres [email protected], podając:

• ID Twojego obszaru roboczego.
• Nazwę integracji.
• Oczekiwane stałe i szczytowe tempo żądań.
• Informację o punktach końcowych (abyśmy mogli zaplanować wydajność dla tych najbardziej obciążających).

Zwiększamy limity na klucz dla klientów korporacyjnych objętych umową, zazwyczaj w ciągu jednego dnia roboczego.

Rozwiązywanie problemów

Nagle otrzymuję błędy 429 na kluczu, który wcześniej działał. Albo Twój kod wpadł w pętlę (najczęstsza przyczyna), albo ktoś inny w obszarze roboczym zaczął używać tego samego klucza. Sprawdź kartę Usage dla klucza API w panelu sterowania, aby zobaczyć wykres żądań na minutę.

Błędy 429 przy pierwszym żądaniu w ciągu dnia. Pule w planie Free resetują się w oknie kroczącym, a nie o północy UTC. Jeśli testowałeś limit wczoraj o 23:59 i pula nie została w pełni uzupełniona do 00:01, pierwszy burst wciąż może być ograniczony. Odczekaj 60 sekund.

Wartość X-RateLimit-Remaining jest ujemna. Przekroczenie limitu burst. Liczba ta mówi Ci, jak bardzo jesteś „na minusie”; pomnóż ją przez 60/limit, aby dowiedzieć się, ile sekund brakuje do powrotu do zera.