Quali sono i limiti di velocità (rate limits)?

Al momento, non applichiamo limiti rigorosi di richieste al secondo. Tuttavia, ci si aspetta un uso corretto per mantenere la qualità del servizio per tutti.

Approccio attuale

Invece di limiti rigidi, incoraggiamo un uso responsabile:

• Distanzia le richieste in modo ragionevole

• Implementa un backoff esponenziale quando si verificano errori

• Usa la cache delle risposte per evitare chiamate ridondanti

• Contattaci se prevedi volumi di traffico elevati

Best practice

Usa la cache in modo aggressivo:

• Salva i risultati di ricerca per le query più comuni

• Conserva localmente i metadati dei media dopo il recupero

• Non chiamare /confirm più volte per lo stesso utente/risorsa

Raggruppa le operazioni:

• Raggruppa insieme le richieste correlate

• Aggiungi piccoli ritardi tra i batch

• Limita le connessioni concorrenti (10-20 è ragionevole)

Gestisci gli errori con attenzione:

• Implementa una logica di retry con backoff esponenziale

• Non riprovare immediatamente in caso di fallimento

• Registra gli errori per il monitoraggio

Tempi di risposta attesi

• Ricerca su /resources: in genere 200-500ms

• Dettagli di /resource: sotto 100ms

• /confirm per la licenza: 300-800ms

Imposta il timeout del client su almeno 30 secondi per gestire occasionali risposte più lente.

Se raggiungi i limiti

Riceverai un errore 429 Too Many Requests. Quando succede:

// Implement exponential backoff
async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        const waitTime = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }
      
      return response;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

Monitora il tuo utilizzo

Traccia l’attività API in Impostazioni → API:

• Visualizza il totale delle richieste effettuate

• Controlla le licenze attive

• Rivedi le tendenze di utilizzo

• Monitora eventuali pattern insoliti

Hai bisogno di limiti più alti?

Se il tuo caso d’uso legittimo richiede volumi elevati di richieste (>1M richieste/mese), contatta il nostro team per discutere:

• La tua applicazione e i pattern di traffico

• Il volume di richieste previsto

• I limiti di velocità garantiti, se necessari