Hlavička Retry-After: jak dlouho čekat před opakováním

Retry-After je hlavička odpovědi HTTP, která vaší aplikaci říká, jak dlouho má čekat, než odešle další požadavek. Hodnota je buď počet sekund, nebo datum HTTP. Když ho rozhraní API odešle, je nejspolehlivější odpovědí na „kdy to můžu zkusit znovu?“, protože pochází ze serveru, který vaši žádost zamítl. Další informace naleznete v dokumentu RFC 9110 oddíl 10.2.3.

Jak Retry-After vypadá

Záhlaví má 2 formáty. Vaše aplikace musí zpracovávat obojí.

Format Example Co to znamená
Seconds Retry-After: 120 Počkejte 120 sekund (2 minuty) od okamžiku, kdy jste dostali odpověď. Hodnota je nezáporné celé číslo.
Datum HTTP Retry-After: Fri, 31 Dec 1999 23:59:59 GMT Před tímto časem požadavek neodesílejte znovu. Datum je vždy v GMT.

Servery odesílají Retry-After tyto stavové kódy:

Status Co Retry-After znamená Source
429 Too Many Requests Jak dlouho čekat, než odešlete nový požadavek. Server to může zahrnovat. RFC 6585, oddíl 4
503 Service Unavailable Jak dlouho se očekává, že bude služba nedostupná. Server ho může obsahovat. RFC 9110, oddíl 15.6.4
413 Content Too Large Pokud je podmínka dočasná, měl by server uvést, jak dlouho je konec. RFC 9110, oddíl 15.5.14
Jakékoli 3xx přesměrování Minimální doba čekání před provedením přesměrování. RFC 9110, oddíl 10.2.3

Záhlaví je volitelné. Některá rozhraní API místo toho používají vlastní hlavičky. Například GitHub vám pomocí x-ratelimit-reset sdělí, kdy se váš limit resetuje. Další informace najdete v tématu Byl překročen limit požadavků rozhraní GitHub API.

Zpracování Retry-After

  1. Přečtěte si obsah v obou formátech. Pokud je hodnota číslo, jedná se o sekundy. V opačném případě ho parsujte jako datum a odečtěte aktuální čas. Pokud je datum již v minulosti, můžete to zkusit znovu hned.
  2. Počkejte alespoň tak dlouho, dokud záhlaví říká. Když to zkusíte znovu dříve, obvykle získáte další 429 nebo 503. Některá rozhraní API stále počítají vaše požadavky, zatímco vás omezují, takže předčasné opakované pokusy můžou čekání prodloužit. Podívejte se například na Microsoft Graph pokyny k omezování.
  3. Pokud záhlaví chybí, přejděte na backoff s jitterem. Po každém neúspěšném pokusu zdvojnásobte dobu čekání, přidejte náhodnou dobu čekání, aby se mnoho klientů nepokoušelo znovu ve stejný okamžik, a omezte maximální dobu čekání.
  4. Omezte opakování. Po několika pokusech vraťte volajícímu chybu.
  5. Zkontrolujte, jestli vám může pomoct opakování pokusu. Některá rozhraní API se vrátí 429 , když se váš kredit nebo limit útraty využije. Čekání to nevyřeší. Příklad najdete v tématu Insufficient_quota OpenAI a credit_balance_exhausted.
function retryDelayMs(response, attempt) {
  const value = response.headers.get('retry-after');
  if (value) {
    const seconds = Number(value);
    const ms = Number.isNaN(seconds) ? Date.parse(value) - Date.now() : seconds * 1000;
    if (!Number.isNaN(ms)) {
      return Math.max(ms, 0);
    }
  }
  // No usable header: exponential backoff with jitter, capped at 30 seconds
  return Math.random() * Math.min(30_000, 1_000 * 2 ** attempt);
}

Mnohá SDK za vás zpracovávají Retry-After, ale pouze dokud nevyčerpají všechny pokusy o opakování. Pak váš kód obdrží chybu.

sada SDK Co ve výchozím nastavení dělá
.NET standardní obslužná rutina odolnosti Opakuje odpovědi 408, 429 a 5xx až 3krát s exponenciálním zpožďováním a kolísáním. Používá se Retry-After pro zpoždění, protože ShouldRetryAfterHeader má jako výchozí hodnotu true.
Microsoft Graph SDKs Používejte Retry-After, když je přítomná, a přejděte na exponenciální prodlevu, když není. Požadavky v dávce JSON se automaticky znovu nezkoušejí.
OpenAI Python SDK Při chybách připojení a odpovědích 408, 409, 429 a 5xx akci zopakuje 2krát s krátkou exponenciální prodlevou. Nastavte max_retries, aby se to změnilo.

Zkontrolujte přesné zásady v dokumentaci sady SDK a otestujte, co se stane po selhání posledního pokusu o opakování.

Jak otestovat, že aplikace správně reaguje na Retry-After

Na Retry-After během vývoje narazíte jen zřídka, a když už k tomu dojde, nemůžete ovlivnit její hodnotu. Takže způsob, jakým to otestujete, tedy rozhoduje o tom, zda chyby najdete dříve, než je najdou vaši uživatelé.

Approach Co najdete Co vám chybí
Počkejte na produkční prostředí Skutečná selhání Všechno, dokud na to uživatel nenarazí
Mockujte API v testech nebo nechte svého programovacího agenta napsat mock Jestli váš kód parsuje hlavičku Zda váš skutečný klient HTTP nebo sada SDK čeká dostatečně dlouho a co rozhraní API skutečně odesílá. Vaše aplikace také potřebuje testovací přepínač pro přístup k mocku.
Volejte skutečné rozhraní API, dokud vás nezačne omezovat Skutečné chování Nemůžete dle potřeby vyvolat odpověď omezenou kvůli limitu a vyčerpáte svou skutečnou kvótu.
Zachyťte skutečný provoz vaší aplikace a vraťte škrcené odpovědi na vyžádání Jestli vaše skutečná sada SDK a zásady opakování pokusů čekají tak dlouho, jak uvádí záhlaví V aplikaci se nic nemění, takže neotestuje váš kód izolovaně. Na to si nechte jednotkové testy.

Vyzkoušejte si ji v aplikaci

Dev Proxy zachytí požadavky vaší aplikace na vámi zvolená rozhraní API a vrátí 429 odpovědi s hlavičkou Retry-After , zatímco vaše aplikace bude dál volat skutečné adresy URL. RetryAfterPlugin si pamatuje, kdy lze každý požadavek omezený kvůli throttlingu zopakovat. Pokud vaše aplikace volá stejnou adresu URL před tímto časem, Dev Proxy to nahlásí a požadavek znovu omezí. Plugin sleduje pouze odpovědi 429.

V souboru chyb pro GenericRandomErrorPlugin nastavte Retry-After hodnotu 429 odpovědi na @dynamic a Dev Proxy vyplní počet sekund a sleduje ji za vás.

Pokud ho chcete vyzkoušet, stáhněte si předvolbu, která používá oba moduly plug-in, a spusťte s ní Dev Proxy:

devproxy config get openai-throttling
devproxy --config-file "~dataFolder/configs/openai-throttling/.devproxy/devproxyrc.json"

Pak aplikaci spusťte obvyklým způsobem a sledujte, co to dělá. Informace o instalaci Dev Proxy najdete v článku Nastavení Dev Proxy.

Další kroky

Otestujte, že moje aplikace správně zpracovává škrcení

Viz také

  • Poslední aktualizace v