Rate limiti

FiskalAPI primjenjuje rate limite kako bi osigurao stabilnost servisa za sve korisnike. Limiti su postavljeni dovoljno visoko da ne utječu na normalnu upotrebu.

Limiti po planu

Plan	Zahtjeva/min	Zahtjeva/dan	Burst
Sandbox	60	10,000	10
Starter	120	50,000	20
Business	300	200,000	50
Enterprise	Custom	Custom	Custom

ℹ️ Burst limit

Burst limit je maksimalan broj zahtjeva u jednoj sekundi. Sprječava da jedna aplikacija "zauzme" sav kapacitet kratkotrajnim spike-om.

Limiti po endpointu

Neki endpointi imaju dodatna ograničenja:

Endpoint	Limit	Razlog
`POST /v1/invoices/fiscalize`	30/min	Ovisi o kapacitetu Porezne
`POST /v1/einvoices/send`	60/min	FINA throttling
`GET /v1/kpd/*`	300/min	Read-only, viši limit
`POST /v1/validate/oib`	300/min	Nema eksterne ovisnosti

Rate limit headeri

Svaki response uključuje headere za praćenje limita:

Response Headers

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 115
X-RateLimit-Reset: 1704294060
Retry-After: 45

Header	Opis
`X-RateLimit-Limit`	Maksimalan broj zahtjeva u periodu
`X-RateLimit-Remaining`	Preostali broj zahtjeva
`X-RateLimit-Reset`	Unix timestamp kada se limit resetira
`Retry-After`	Sekunde do sljedećeg dozvoljenog zahtjeva (samo kod 429)

Što se događa kad prekoračite limit?

Dobijete 429 Too Many Requests response:

429 Too Many Requests

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Prekoračen broj zahtjeva. Pokušajte ponovno za 45 sekundi.",
    "doc_url": "https://fiskalapi.hr/docs/reference/limiti"
  }
}

Best practices

✓Implementirajte exponential backoff

Kad dobijete 429, pričekajte Retry-After sekundi. Ako retry i dalje ne uspije, udvostručite vrijeme čekanja.

✓Koristite batch endpointe

Za OIB validaciju i KPD lookup, koristite batch verzije ako trebate provjeriti više vrijednosti odjednom.

✓Cache-irajte odgovore gdje ima smisla

KPD šifre se ne mijenjaju često. Cache-irajte lookup rezultate lokalno.

✓Pratite X-RateLimit-Remaining

Proaktivno usporite zahtjeve kad vidite da se limit približava nuli.

Primjer implementacije

Node.js — Rate limit aware client

class RateLimitedClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.remaining = Infinity;
    this.resetTime = 0;
  }

  async request(endpoint, options = {}) {
    // Proaktivno čekaj ako smo blizu limita
    if (this.remaining < 5) {
      const waitTime = this.resetTime - Date.now();
      if (waitTime > 0) {
        await this.sleep(waitTime);
      }
    }

    const response = await fetch(`https://api.fiskalapi.hr${endpoint}`, {
      ...options,
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
        ...options.headers,
      },
    });

    // Update rate limit info
    this.remaining = parseInt(response.headers.get('X-RateLimit-Remaining') || '100');
    this.resetTime = parseInt(response.headers.get('X-RateLimit-Reset') || '0') * 1000;

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      await this.sleep(retryAfter * 1000);
      return this.request(endpoint, options); // Retry
    }

    return response;
  }

  sleep(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

Povećanje limita

Ako vam standardni limiti nisu dovoljni:

Nadogradite na viši plan (Business ili Enterprise)
Kontaktirajte nas za custom limite
Optimizirajte korištenje (batch, caching)

Za Enterprise planove s custom limitima: [email protected]

Monitoring

U dashboardu možete vidjeti:

Ukupan broj zahtjeva (dnevno, mjesečno)
Koliko puta ste pogodili rate limit
Prosječno vrijeme odgovora
Uspješnost zahtjeva (success rate)

Webhook rate_limit.warning se šalje kad dosegnete 80% dnevnog limita.