Limity API i kwoty — Polska
Limity token-bucket, zachowanie burst i obsługa 429 dla REST API Corp-Merch w Polska.
Architektura — Limity per-klucz, per-trasa dla Polska
Każdy klucz API ma własny token bucket na trasę. Domyślnie: Standard 600 req/min na /v1/orders i /v1/invoices, 1 200 req/min na read-only; Pro 10x. Burst 2x dozwolony przez 10 sekund. Odpowiedzi z nagłówkami X-RateLimit-Limit, -Remaining, -Reset. Wystawianie faktur KSeF jest asynchroniczne i nie ma limitu na submit — tylko na polling statusu. Obliczenia VAT 23% bez limitu.
Jak to zintegrować — Odpowiedzi 429 i Retry-After
Przy przekroczeniu zwracamy 429 Too Many Requests z nagłówkiem Retry-After w sekundach. Nasze SDK obsługują to wykładniczym backoffem z jitterem; w klientach custom powiel tę logikę i nie pętl busy-loop. Trwałe 429 > 5 minut automatycznie notyfikują nasz zespół CS — wolimy podnieść limit niż zobaczyć awarię.
Eksploatacja i przypadki brzegowe — Kwoty i fair use
Poza limitami, miesięczne kwoty ograniczają zamówienia, faktury i webhooki na tenant — dopasowane do umowy. Soft quota ostrzegają na 80% i 100% przez dashboard i email; hard quota (rzadko, tylko trial) odrzucają z 402 Payment Required. Odczyty katalogu i polling statusu Krajowy System e-Faktur (KSeF) bez limitu w planach płatnych.
FAQ
Czy mogę dostać wyższy limit?
Tak — dla Pro i Enterprise dopasowujemy limity do kontraktowych wolumenów. Zgłoś się do supportu z profilem trwałego obciążenia.
Czy read-only mają wyższy limit?
Tak — endpointy read (GET /v1/catalog, GET /v1/orders) mają domyślnie 2x limit zapisów.
A webhooki?
Throughput webhooków ma osobny budżet — do 50/s na endpoint z backpressure; za inbound nie płacisz.
Obsługa burst?
Token bucket pozwala na 2x burst przez ~10 sekund, potem obowiązuje limit steady-state. Dobre dla jobów końca miesiąca.
Polling KSeF?
Polling /v1/invoices/{id} ma rate-limit jak inne read; rekomendujemy webhooki dla potwierdzenia KSeF.