API sebességkorlátok

Minden kérés a https://api.primecal.eu/api felé sebességkorlátozott. A korlátok attól függnek, ki hívja (a szinted) és mit hív (a végpont kategóriája).

Szintek

Szint	Ki kapja
guest	Hitelesítetlen kérések
user	Bejelentkezett felhasználók és a legtöbb API-kulcs
premium	Rendszeradminisztrátorok, és Enterprise vagy Store használati csomagon
lévő felhasználók

A szinted automatikusan feloldódik az auth-kontextusodból — nincs mit beállítani. Egy API-kulcs saját szintet is hordozhat, függetlenül a hívó felhasználó csomagjától.

Kategóriák és korlátok

Minden végpont az útvonala alapján egy kategóriába esik. A korlátok kérés/60 másodperces ablak formátumban vannak, hacsak másképp nincs jelezve.

Kategória	Illeszkedik	guest	user	premium
auth	/auth/* (a lenti útvonalak kivételével)	8	20	40
oauth	/auth/google, /auth/microsoft	60	120	240
availability	/auth/username-availability, /auth/email-availability, bármely /availability útvonal	30	80	180
booking	/reservations/*, /booking/*, /public-booking/*	20	120	300
admin	/admin/*	4	30	120
default	minden más	40	180	450

Az availability token-bucket algoritmust használ (rövid kilengéseket enged); minden más kategória csúszóablakot (sliding window) használ.

A korlátok visszaélés-észlelés hatására eltolódhatnak

Egy kérés effektív korlátja automatikusan csökkenhet, ha a PrimeCal visszaélés-megelőzési rendszere magas kockázati pontszámot lát az IP-dhez/identitásodhoz. A fenti táblázat az alapérték, nem egy minden pillanatban érvényes szigorú garancia.

Válaszfejlécek

Minden válasz — sikeres vagy nem — tartalmazza:

Fejléc	Jelentés
X-RateLimit-Limit	A korlátod ehhez a kéréskategóriához és szinthez
X-RateLimit-Remaining	Hátralévő kérések a jelenlegi ablakban
X-RateLimit-Reset	Unix időbélyeg (másodperc), amikor az ablak visszaáll
X-RateLimit-Policy	<algoritmus>;w=<ablakMásodperc>;tier=<szint>;category=<kategória>

Amikor korlátozva vagy

A korláton felüli kérés HTTP 429-et ad vissza Retry-After fejléccel (másodperc) és egy JSON törzzsel:

{
  "statusCode": 429,
  "message": "Too many requests",
  "details": {
    "tier": "user",
    "category": "default",
    "retryAfterSeconds": 12
  }
}

Várj legalább retryAfterSeconds-ot az újrapróbálkozás előtt. Ne próbálkozz újra szoros ciklusban — az az ugyanazon ablakon belül tart.

Gyakorlati útmutatás

• Kötegeld és gyorsítótárazd, ahol tudod, különösen az admin kategóriával szemben — a korlátai szándékosan alacsonyak.
• Hitelesíts — a guest szint a legkorlátozóbb minden kategóriában. A bejelentkezés vagy egy API-kulcs használata nagyjából megduplázza a kereted a legtöbb kategóriában.
• Egy 429 nem jelenti, hogy valami elromlott — azt jelenti, hogy gyorsabban hívsz, mint amit a szinted engedélyez. Ellenőrizd az X-RateLimit-Remaining-et, mielőtt nullára csökkenne, ahelyett hogy egy 429 után reagálnál.
• Ha az integrációdnak valóban magasabb korlátra van szüksége, a magasabb használati csomagok (Enterprise, Store) automatikusan premium szintet kapnak — lásd: Csomagok és árak.

Kapcsolódók

• API áttekintés
• Hitelesítés API