Limiti di frequenza

I limiti di frequenza proteggono il tuo saldo e il servizio. I limiti si misurano in richieste al minuto (RPM) per chiave API, e le chiavi possono avere anche un limite di spesa giornaliero in USD.

Limiti per piano

Passa a un piano superiore nella pagina dei prezzi per aumentare il tuo limite.

Limiti per chiave

Quando crei o modifichi una chiave in Chiavi API puoi impostare:

La finestra RPM è di un minuto ed è calcolata per chiave, quindi chiavi separate per app separate non condividono lo stesso limite, ma ogni chiave resta comunque vincolata al limite del tuo piano.

Header dei limiti

Ogni risposta di generazione (riuscita o con errore) indica a che punto sei, così puoi rallentare prima di raggiungere il limite:

Anche i client browser possono leggerli (sono in Access-Control-Expose-Headers).

Picchi e concorrenza

Le richieste oltre il limite non vengono rifiutate subito: attendono in coda e partono appena la finestra di un minuto si libera. Per account girano fino a 10 richieste contemporaneamente; le altre aspettano che una finisca. Prima di partire, il costo massimo stimato della richiesta viene riservato dal saldo insieme a quello delle richieste in corso, quindi le richieste parallele non spendono mai più di quanto hai. Una richiesta che non riesce a partire entro 60 secondi restituisce 429 (rate_limited o concurrency_limit) con Retry-After; se il suo costo non rientra più nel saldo, restituisce 402 insufficient_balance.

Ritentativi sicuri con Idempotency-Key

Dopo un errore di rete potresti non sapere se la richiesta è arrivata. Invia un header Idempotency-Key (una stringa univoca fino a 120 caratteri, per esempio un UUID) e riprova con la stessa chiave: se la prima richiesta è già stata inviata al modello, il nuovo tentativo restituisce 409 idempotency_conflict invece di eseguire e addebitare il lavoro due volte. Se la prima è fallita prima di raggiungere il modello, la chiave viene liberata e il nuovo tentativo funziona normalmente. Una chiave è utilizzabile una volta per account per 24 ore.

curl https://api14.com/api/v1/images/generations \
  -H "Authorization: Bearer $API14_KEY" \
  -H "Idempotency-Key: 6f1c2a3e-order-1842" \
  -H "Content-Type: application/json" \
  -d '{"model": "black-forest-labs/flux-3-image", "prompt": "a red bicycle"}'

Quando raggiungi un limite

Troppe richieste

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "error": {
    "message": "Rate limit of 5 requests per minute exceeded.",
    "type": "rate_limit_error",
    "code": "rate_limited"
  }
}

Attendi il numero di secondi indicato in Retry-After, poi riprova. Gli SDK ufficiali di OpenAI ripetono automaticamente le risposte 429 con backoff (due tentativi per impostazione predefinita; configurabile con maxRetries / max_retries).

Limite di spesa giornaliero

{
  "error": {
    "message": "This API key reached its daily spend limit.",
    "type": "rate_limit_error",
    "code": "daily_limit_reached"
  }
}

Riprovare non serve fino al giorno UTC successivo. Aumenta o rimuovi il limite giornaliero della chiave in Chiavi API se si tratta di traffico previsto.

Limiti dell'upstream

I provider hanno i propri limiti, più restrittivi per le varianti di modello :free. Quando un provider limita una richiesta, il suo 429 ti viene inoltrato. Usa i fallback di modello o l'instradamento dei provider per distribuire il carico tra più provider.

Gestire i limiti nel codice

• Rispetta il Retry-After e riprova con backoff esponenziale e jitter.
• Distingui rate_limited (riprova più tardi) da daily_limit_reached e insufficient_balance (riprovare non serve).
• Metti in coda i job in background invece di lanciarli tutti insieme.
• Usa lo streaming per le risposte lunghe: una richiesta in streaming conta come una sola richiesta.

import time
from openai import OpenAI, RateLimitError

client = OpenAI(base_url="https://api14.com/api/v1", api_key="sk-api14-...", max_retries=0)

for attempt in range(5):
    try:
        r = client.chat.completions.create(model="openai/gpt-5-mini", messages=[{"role": "user", "content": "Hi"}])
        break
    except RateLimitError as e:
        if e.code == "daily_limit_reached":
            raise
        time.sleep(int(e.response.headers.get("retry-after", 2 ** attempt)))

Vedi Errori per tutti i codici di stato.