Limiti di frequenza dell'API

I 5 livelli

Ogni richiesta passa attraverso cinque controlli. Il primo che rifiuta vince.

Tetti giornalieri per endpoint

Alcuni endpoint hanno limiti più stretti perché consumano tempo significativo di CPU o GPU:

Limite di dimensione file

• 200 MB per file per l'API (rispetto ai 100 MB del sito web).
• Alcuni strumenti AI pesanti hanno limiti interni più bassi — ad esempio upscale-image è limitato a 20 MB per mantenere le esecuzioni GPU sotto i 2 minuti.

Headers in ogni risposta

Ogni risposta API riuscita include i seguenti headers così puoi monitorare la tua quota senza interrogare /api/v1/limits:

X-RateLimit-Limit-Day: 1000
X-RateLimit-Remaining-Day: 873
X-RateLimit-Reset-Day: 1775865600     # unix timestamp
X-RateLimit-Limit-Hour: 150
X-RateLimit-Remaining-Hour: 142
X-RateLimit-Limit-Endpoint: 50
X-RateLimit-Remaining-Endpoint: 38

Cosa succede quando raggiungi un limite

L'API restituisce 429 Too Many Requests con un header Retry-After (in secondi) e un header X-RateLimit-Reason che indica quale livello è stato raggiunto:

HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-RateLimit-Reason: cooldown

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded (cooldown). Retry after 1 seconds.",
    "details": { "reason": "cooldown", "retry_after": 1 }
  }
}

Valori possibili di X-RateLimit-Reason: cooldown, burst, hourly, daily, endpoint:<name>, banned.

Escalation al ban

L'abuso ripetuto attiva un ban temporaneo. Nello specifico: 10 rifiuti di rate limit entro 1 ora dallo stesso IP → ban di 24 ore con HTTP 403 Forbidden ed error.code: BANNED.

Se pensi di essere stato bannato ingiustamente (ad esempio perché condividi un IP con molti utenti), contattaci su /contact e valuteremo il caso.

Buone pratiche per evitare il throttling

• Attendi almeno 1 secondo tra richieste consecutive (o usa l'header Retry-After sui 429).
• Usa gli endpoint batch per il lavoro massivo: POST /api/v1/batch gestisce fino a 20 file in una singola chiamata HTTP (ogni file conta comunque sulla tua quota giornaliera, ma risparmi round trip).
• Controlla gli headers: quando X-RateLimit-Remaining-Day scende sotto 100, rallenta o metti in cache i risultati.
• Ispeziona il tuo utilizzo in qualsiasi momento con GET /api/v1/limits — questo endpoint NON conta sulla tua quota.
• Non riprovare istantaneamente su un 429 — rispetta Retry-After. I retry immediati possono innescare l'escalation al ban.

Servono limiti più alti?

I limiti attuali sono valori predefiniti MVP. Stiamo osservando l'uso reale e li aggiusteremo in base alla domanda. Se hai un caso d'uso legittimo che richiede quote più alte, contattaci su /contact.

Un futuro piano a pagamento potrebbe offrire quote dedicate, code prioritarie e ritenzione file più lunga — ma il piano gratuito rimarrà sempre disponibile.