Gemini API vrací 429: nový klíč obvykle problém nevyřeší

Chyba 429 RESOURCE_EXHAUSTED v Gemini API ukazuje na překročený limit. Podle pravidel limitů Gemini API se kvóty uplatňují na projekt, nikoli na jednotlivý API klíč. Vytvoření dalšího klíče ve stejném projektu proto obvykle nepomůže; zjistěte, zda požadavek zastavil počet volání, vstupní tokeny, denní kvóta nebo tempo útraty.

Pro obnovení provozu potřebujete přečíst detail chybové odpovědi a porovnat ho s aktivními limity příslušného modelu v Google AI Studio. Krátkodobé omezení může povolit po prodlevě, zatímco vyčerpaná denní kvóta vyžaduje odložení práce do její obnovy nebo změnu dostupného limitu. Opakovat bez rozlišení oba případy stejnou smyčkou znamená posílat další požadavky do stále platného omezení.

Co vyčíst z celé chybové odpovědi

Zaznamenejte HTTP kód a pole error.status, error.message a error.details, pokud jsou v odpovědi přítomna. Samotné RESOURCE_EXHAUSTED neurčuje, který čítač byl překročen. V poli details hledejte záznam typu QuotaFailure a jeho violations; u každého porušení si všimněte quotaMetric, quotaId a quotaDimensions. Samostatný záznam RetryInfo může obsahovat retryDelay.

Specifikace detailů google.rpc popisuje quotaMetric jako počítanou metriku, quotaId jako identifikátor limitu a quotaDimensions jako jeho dimenze; retryDelay je minimální doporučená doba čekání před opakováním. Specifikace také připouští více položek violations. Jsou to významy polí, nikoli příslib, že je každá odpověď Gemini API všechny vrátí.

Nejdříve projděte všechna porušení, protože požadavek může současně narazit na více mezí. Název metriky rozliší například požadavky od vstupních tokenů; identifikátor a popis limitu mohou napovědět, zda jde o minutu nebo den. Dimenze čtěte spolu s modelem, který aplikace skutečně volala. Pokud pole chybí nebo jejich názvy nestačí k bezpečnému závěru, porovnejte čas chyby a využití s aktivními limity projektu v AI Studio.

Čtyři omezení, čtyři různé zásahy

Požadavky za minutu: omezte rychlost odesílání a souběh volání pro dotčený projekt a model. Společná fronta nebo regulátor tempa pomůže držet pod kontrolou i více instancí aplikace. Samostatný backoff v každé instanci může požadavky jen přesunout na podobný okamžik, kdy se znovu střetnou s týmž limitem. Do plánované zátěže započítejte také opakované pokusy.

Vstupní tokeny za minutu: sledujte objem odesílaného kontextu, nejen počet volání. Dlouhé prompty nebo opakovaně připojovaný kontext mohou vyčerpat tokenový limit, i když je počet požadavků nízký. Zkraťte nepotřebné části vstupu nebo rozložte práci v čase. Pouhé snížení souběhu nemusí stačit, pokud jednotlivé požadavky zůstávají příliš velké.

Požadavky za den: krátká prodleva denní čítač neobnoví. Denní kvóta Gemini API se obnovuje o půlnoci pacifického času, takže pro provoz v Česku není rozhodující místní půlnoc. Odložte úlohy do dalšího období, ověřte limit konkrétního modelu nebo podle možností účtu požádejte o jeho zvýšení. Další klíč patřící témuž projektu vyčerpanou kvótu nevynuluje.

Tempo útraty: u účtů, na které se tento limit vztahuje, se výdaje posuzují v průběžném desetiminutovém okně a jeho překročení také vrací 429 RESOURCE_EXHAUSTED. Omezte četnost nákladných volání, velikost kontextu nebo délku výstupu. Jde o jiné časové okno než u denní kvóty; při hledání příčiny proto porovnejte i způsob účtování a využití daného projektu. Dostupné limity se liší podle modelu a úrovně účtu.

Jak naložit s prodlevou a chybějícím detailem

Je-li přítomno retryDelay, neodesílejte stejný požadavek dříve, než uvedená prodleva uplyne. Hodnota ale sama neurčuje druh vyčerpané kvóty a nezaručuje, že další pokus uspěje. Pokud QuotaFailure ukazuje na denní limit, dejte přednost odložení úlohy; u krátkodobého limitu snižte také přítok nových požadavků, jinak se po čekání rychle vrátíte ke stejné chybě.

Bez použitelného detailu nelze z kódu 429 bezpečně vyčíst, zda rozhodl minutový, tokenový, denní nebo výdajový limit. Zachovejte původní odpověď pro diagnostiku a ověřte využití projektu; přechodně lze zkusit jen omezený počet opakování. Chybu 503 UNAVAILABLE posuzujte zvlášť jako možnou dočasnou nedostupnost služby. Čekání může pomoci i tam, ale neříká nic o stavu denní kvóty projektu.

Omezený exponenciální backoff s jitterem

Průvodce řešením chyb Gemini API doporučuje u přechodných chyb exponenciální backoff, náhodnou odchylku prodlevy neboli jitter a pevný strop opakování. U přímých REST volání musí tuto politiku zajistit klient. Oficiální Python SDK už přechodné chyby automaticky opakuje, proto před přidáním vlastní vrstvy zjistěte, jaké pokusy provádí knihovna. Vnořené retry smyčky mohou prodloužit čekání a poslat více volání, než aplikace zamýšlí.

Následující pseudokód popisuje jednu klientskou politiku. Parametry baseDelay, maxDelay, maxAttempts a deadline nastavte podle časového rozpočtu aplikace; maxAttempts označuje celkový počet odeslání včetně prvního pokusu.

1. Odešli požadavek. Při úspěchu vrať výsledek. Při chybě, kterou nemá smysl opakovat, vrať chybu volajícímu.
2. Při 429 projdi všechna dostupná porušení kvóty. Ukazují-li na vyčerpanou denní kvótu, odlož úlohu mimo krátkou retry smyčku. U jiné přechodné chyby pokračuj jen tehdy, pokud zbývá další pokus.
3. Pro následující pokus vypočti exponenciální prodlevu z baseDelay a pořadí pokusu, omez ji hodnotou maxDelay a přidej náhodný jitter. Výsledné čekání musí být alespoň tak dlouhé jako retryDelay, pokud jej server poskytl.
4. Přesáhlo-li by čekání deadline, další pokus neprováděj a předej chybu nebo úlohu řízené frontě. Jinak počkej, odešli znovu a po dosažení maxAttempts skonči.

Jitter rozloží opakované pokusy souběžných klientů v čase; strop pokusů a deadline brání nekonečné smyčce. Pokud server doporučí delší retryDelay, než dovoluje časový rozpočet aplikace, nekracťte ho kvůli okamžitému pokusu: úlohu odložte nebo vraťte volajícímu informaci o čekání. Samotný backoff navíc nereguluje nové požadavky. Trvale přetížený projekt potřebuje upravit jejich tempo nebo objem podle limitu, který chybová odpověď odhalila.