Limity požadavků

Limity podle tarifu

Počítadlo se resetuje v klouzavém 60minutovém okně, ne na celou hodinu. Každý API klíč má vlastní počítadlo — klíče na stejném účtu si kvótu nedělí.

Odpověď 429

Při překročení limitu vrátí BriefGate HTTP 429:

{
  "error": "rate_limited",
  "message": "Rate limit of 60 requests/hour for the free plan reached. Retry after 1847s, or reduce polling frequency — use webhooks instead of polling get_intake_status in a loop.",
  "request_id": "req_abc123"
}

Hlavička Retry-After obsahuje počet sekund, které je potřeba počkat před dalším pokusem. Řiďte se jí, místo abyste se dotazovali v pevném intervalu.

Problém agentní smyčky

Agenti běžící ve smyčce vyčerpají limit 60 req/h na tarifu Free během pár minut, pokud v každé iteraci zavolají get_intake_status. Agent, který se ptá na stav každých 5 sekund, udělá 720 požadavků za hodinu — dvanáctinásobek limitu tarifu Free.

Správné řešení jsou webhooky. Zaregistrujte si endpoint pro události intake.completed a item.submitted. BriefGate ho zavolá, když se něco změní. Vy voláte BriefGate jen tehdy, když na tu změnu potřebujete zareagovat.

S webhooky:

• Nula dotazů, dokud klient nic neudělá
• Prakticky okamžité upozornění, jakmile klient něco odešle
• Agent se probudí, jednou zavolá get_intake_results a staví dál

Registrace webhook endpointu:

curl -X POST https://api.briefgate.dev/v1/webhooks \
  -H "Authorization: Bearer bg_live_xxxxx" \
  -d '{"url":"https://yourapp.com/webhooks","events":["intake.completed","item.submitted"]}'

Kompletní návod na nastavení najdete v kapitole Webhooky.

Doporučené intervaly dotazování

Pokud webhooky ve vašem nasazení nejsou k dispozici (třeba když běžíte lokálně bez veřejné URL), dotazujte se nejvýš takto často, ať vám zbyde rezerva i na ostatní volání API:

Pro vystavení lokálního webhook endpointu při vývoji použijte ngrok nebo podobný tunelovací nástroj.

Na co se limit vztahuje

Limity platí na API klíč, ne na účet.

• Každý klíč na stejném účtu má vlastní nezávislé počítadlo
• Pro různé agentní session a CI pipeline používejte samostatné klíče — nebudou si navzájem překážet
• Další klíče vytvoříte přes GET /v1/auth/keys (výpis) a POST /v1/auth/keys (vytvoření)

Například: jeden klíč pro session v Claude Code, druhý pro CI pipeline, třetí pro skripty ověřující webhooky.

Testovací klíče

Klíče začínající bg_test_ používají oddělený limitní koš. Nespotřebovávají produkční kvótu a pracují proti testovacímu prostředí.

Testovací klíče vracejí syntetická data a neposílají klientům skutečné e-maily. Použijte je pro vývoj a CI.

# Testovací klíč — bezpečný pro automatizované testy, nesahá na produkční limity
BRIEFGATE_API_KEY=bg_test_xxxxx

Při nasazení do produkce přepněte na klíč bg_live_.