Rate limits

Limity są nakładane per klucz API (lub per IP, dla niezalogowanych). Plan API daje 600 req/min i 200 000 req/dzień.

Trzy okna jednocześnie

Każde żądanie konsumuje slot w trzech oknach: per minute, per day, per month (to ostatnie tylko dla zasobów objętych quotą planu - walidacja, korekta). Odpowiedź zawiera headery dla wszystkich aktywnych okien, dzięki czemu możesz przewidywać throttling:

http

HTTP/1.1 200 OK
X-RateLimit-Limit-Minute: 600
X-RateLimit-Used-Minute: 12
X-RateLimit-Remaining-Minute: 588
X-RateLimit-Reset-Minute: 1715000060
X-RateLimit-Limit-Day: 200000
X-RateLimit-Used-Day: 1450
X-RateLimit-Remaining-Day: 198550
X-Quota-Month-Limit: 100000
X-Quota-Month-Used: 12340
X-Quota-Month-Remaining: 87660

Domyślne limity per plan

Plan	req / minuta	req / dzień	Walidacje / miesiąc
free	60	1 000	50
pro	300	50 000	10 000
api	600	200 000	unlimited

Klucze sandbox (nk_test_*) mają identyczne limity per minute/day, ale nie liczą się do quoty miesięcznej.

Co się dzieje przy przekroczeniu

Serwer zwraca HTTP 429 RATE_LIMITED z polem Retry-After w sekundach. Jeśli przekroczyłeś quotę planu (nie chwilowy minutowy throttle), kod jest QUOTA_EXCEEDED i serwer emituje webhook quota.exceeded - możesz wykorzystać go do alertu w PagerDuty / Slacku.

http

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit-Minute: 600
X-RateLimit-Used-Minute: 601
X-RateLimit-Remaining-Minute: 0
X-RateLimit-Reset-Minute: 1715000060
Content-Type: application/json

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Limit minutowy klucza został wyczerpany. Spróbuj ponownie za 30 sekund."
  },
  "meta": { "request_id": "a3f9c1d8b2e7f4a1" }
}

Wzorzec klienta

Zawsze honoruj Retry-After. Nie testuj limitów spinnerem - zostaniesz wytrottlowany. Najlepiej użyć SDK które robi to za Ciebie:

typescript

try {
  await client.validate.run({ xml });
} catch (e) {
  if (e instanceof NaprawKsefRateLimitError) {
    const wait = e.retryAfterSeconds ?? 60;
    log.warn({ wait, used: e.rateLimit?.used }, "throttled");
    await sleep(wait * 1000);
    // retry…
  } else {
    throw e;
  }
}

SDK retry policy

Oba SDK (TS, PHP) automatycznie ponawiają 408/425/429/5xx z exponential backoff (max 3 razy domyślnie), respektując Retry-After na 429 i 503. Wyłącz to ustawiając maxRetries: 0.

Potrzebujesz wyższych limitów?

Klient z planu API + dedykowanym wsparciem może podnieść limity minutowe i dzienne pod swoje SLA - napisz na support@naprawksef.pl z opisem use case'u.