Vai al contenuto principale
OrcaRouter applica i limiti di velocità a livello di workspace, non per chiave API. Tutte le chiavi appartenenti allo stesso workspace attingono dallo stesso bucket. Quando il limite viene superato ricevi una risposta HTTP 429 Too Many Requests con un header Retry-After.

​
Perché lo scope è il workspace

I workspace sono il modo in cui OrcaRouter raggruppa chiavi, membri e fatturazione che appartengono a un singolo team o individuo. Limiti condivisi all’interno di un workspace rendono il traffico prevedibile man mano che il tuo team cresce: aggiungere una nuova chiave (o un nuovo membro) non moltiplica il tuo budget condiviso. Se hai bisogno di un limite più alto, aggiorna il piano del workspace. OrcaRouter non espone limiti di velocità per modello ai chiamanti — il gateway si comporta come un singolo provider logico dal punto di vista della tua applicazione, in coerenza con l’opacità del provider. Il throttling interno verso i provider upstream avviene in modo trasparente e non fa parte del contratto pubblico.

​
Risposta

Una richiesta limitata restituisce sempre: 
HTTP/1.1 429 Too Many Requests
Retry-After: <seconds>
Alcuni percorsi di rate-limit includono anche un corpo JSON che spiega il limite raggiunto; altri (il bucket workspace fast-path) restituiscono solo lo status code e gli header. Non dipendere dalla forma del corpo — controlla lo status code 429 e leggi Retry-After. Quando è presente un corpo, segue l’envelope compatibile con OpenAI con error.type impostato a orcarouter_api_error. Il error.message può essere localizzato (attualmente cinese) — vedi Errori per la struttura dell’envelope. Retry-After è in secondi. È la durata della finestra di rate-limit (conservativo — sicuro attendere esattamente quel tempo); la finestra successiva avrà il budget pieno. Riprovare immediatamente senza attendere fallirà di nuovo.

​
Comportamento client raccomandato

  1. Su 429, leggi Retry-After.
  2. Attendi quel numero di secondi.
  3. Riprova la stessa richiesta.
  4. Se si verifica un secondo 429, aumenta l’attesa di 2× (backoff esponenziale) fino a 60 secondi.
  5. Se vedi 429 ripetutamente, considera di suddividere il traffico tra più modelli con extra_body.models — vedi Fallback dei modelli.
Gli SDK Python e TypeScript di OpenAI gestiscono Retry-After automaticamente per impostazione predefinita. Non hai bisogno di codice personalizzato a meno che tu non abbia disabilitato i retry.

​
Reattivo, non predittivo

OrcaRouter non restituisce header X-RateLimit-Remaining / X-RateLimit-Reset, quindi non puoi controllare preventivamente quanto budget rimane. Tratta il 429 come segnale — fai backoff quando lo vedi, poi riprendi.