Rate limit

Ogni chiave API ha un limite sostenuto di richieste al secondo derivato dal tuo piano (Free 1 req/s → Max 60 req/s — vedi Prezzi). I limiti sono applicati con un token bucket: i burst fino alla tua capacità al minuto sono consentiti, poi le richieste vengono livellate alla tariffa sostenuta.

Quando sei limitato

{ "error": "rate_limited", "retry_after_ms": 850 }

HTTP 429, error: "rate_limited".
retry_after_ms ti dice il tempo minimo di attesa prima di ritentare.
L’header x-ratelimit-remaining su ogni risposta riporta quante richieste rimangono in questo minuto.

Concorrenza

Oltre alla tariffa al secondo, c’è un limite sulle richieste in volo. Se invii molte richieste contemporaneamente potresti vedere:

409 request_in_progress — una richiesta idempotente identica è già in esecuzione.
503 too_many_concurrent_requests — troppe richieste concorrenti in volo; applica il backoff e ritenta.

Gestire i limiti

Rispetta retry_after_ms; altrimenti usa il backoff esponenziale con jitter.
Mantieni un limite di concorrenza lato client allineato alla tariffa del tuo piano.
Gli SDK ufficiali ritentano 429/503 automaticamente.