Limiti di frequenza

Comprendi i limiti di frequenza dell'API FreeFileTools e come gestirli nella tua applicazione.

Limiti del piano gratuito

Limite	Valore
Richieste all'ora	`50`
Dimensione massima del file per richiesta	`25 MB`
Finestra del limite di frequenza	`Rolling 1 hour`

Il limite di frequenza viene applicato per API key. Ogni chiave ha il proprio contatore indipendente che si reimposta su base oraria mobile.

Quando i limiti di frequenza vengono superati

Quando superi il limite di frequenza, l'API restituisce una risposta 429 Too Many Requests:

json

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded the rate limit of 50 requests per hour. Please try again later.",
  "retryAfter": 1742
}

Il campo retryAfter indica il numero di secondi da attendere prima di effettuare un'altra richiesta.

Intestazioni di risposta del limite di frequenza

Ogni risposta API include intestazioni per aiutarti a monitorare l'utilizzo del limite di frequenza:

Intestazione	Descrizione
`X-RateLimit-Limit`	Numero massimo di richieste consentite all'ora (50)
`X-RateLimit-Remaining`	Numero di richieste rimanenti nella finestra corrente
`Retry-After`	Secondi da attendere prima di riprovare (solo nelle risposte 429)

Esempio di intestazioni di risposta

http

HTTP/1.1 200 OK
Content-Type: image/jpeg
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 42

Consigli per rimanere nei limiti

Controlla le richieste rimanenti

Monitora l'intestazione X-RateLimit-Remaining per sapere quante richieste ti rimangono.

Implementa il backoff esponenziale

Quando ricevi una risposta 429, attendi e riprova con ritardi crescenti invece di bombardare l'API.

Memorizza i risultati nella cache

Se stai elaborando gli stessi file ripetutamente, memorizza i risultati nella cache locale per evitare chiamate API non necessarie.

Raggruppa con saggezza

Per l'elaborazione in batch, distribuisci le richieste nel tempo invece di inviarle tutte contemporaneamente.

Esempio: Gestione dei limiti di frequenza in JavaScript

javascript

async function apiCall(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get("Retry-After") || "60");
      console.log(`Rate limited. Waiting ${retryAfter} seconds...`);
      await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
      continue;
    }

    return response;
  }

  throw new Error("Max retries exceeded");
}