Chyby + omezení počtu požadavků

Jedna obálka chyby napříč všemi endpointy. Standardní stavové kódy HTTP + strukturovaný řetězec code pro programové porovnávání. Hlavičky omezení počtu požadavků v každé odpovědi, abyste mohli regulovat tempo dříve, než narazíte na 429.

Obálka chyby

{
  "detail": "Human-readable summary.",
  "code": "billing.subscription_past_due",
  "field_errors": {
    "scheduled_for": ["Must be a future ISO 8601 timestamp."]
  }
}

detail — vždy přítomen, bezpečné zobrazit lidem (je přeložen tam, kde je k dispozici příslušný jazyk).
code — přítomen u rozlišitelných chybových stavů. Stabilní napříč verzemi API; porovnávejte podle něj pro logiku opakování.
field_errors — přítomen pouze u validačních selhání 400. Mapa název pole → seznam zpráv.

Matice stavových kódů

Stav	Třída	Opakovat?	Časté příčiny
400	Validace	Ne	Chybějící povinné pole, špatný formát, porušení obchodního pravidla
401	Autentizace	Ne	Chybějící / špatné / odvolané přihlašovací údaje
402	Fakturace	Ne	Předplatné po splatnosti, dosažen limit bezplatného plánu
403	Oprávnění	Ne	Přihlašovacím údajům chybí oprávnění nebo je zdroj v jiné organizaci
404	Nenalezeno	Ne	Zdroj neexistuje nebo není viditelný pro vaše přihlašovací údaje
409	Konflikt	Někdy	Neshoda při opakovaném použití Idempotency-Key, porušení stavového automatu
422	Nezpracovatelné	Ne	Sémanticky neplatná kombinace platných polí
429	Omezení počtu požadavků	Ano, s odstupem	Dosažen limit na přihlašovací údaje nebo na organizaci
500	Chyba serveru	Ano, s odstupem	Neočekávané — pokud přetrvává, otevřete tiket
502 / 503 / 504	Přechodné	Ano, s odstupem	Upstream / nasazení / zátěž

Významné chybové kódy

Kód	Stav	Co znamená
`billing.subscription_past_due`	402	Předplatné organizace u Stripe je po splatnosti. Nasměrujte administrátora na `/admin/billing`.
`billing.free_plan_minutes_exhausted`	402	Úroveň Free / Pilot vyčerpala svých 5 inspekcí.
`billing.signature_pack_exhausted`	402	Kredity balíčku podpisů vyčerpány; plaťte za jednotlivé podpisy nebo kupte další balíček.
`permission_denied`	403	Přihlašovacím údajům chybí oprávnění. Viz `field_errors.required_scope`.
`idempotency.key_mismatch`	409	Stejný klíč, jiné tělo. Použijte nový klíč.
`session.already_ended`	409	Volání `end` na relaci, která není otevřená (obvykle bezpečné — `end` je idempotentní, toto je pro okrajové případy).
`kyb.not_verified`	403	Podpis QES požadován u organizace, která neprošla KYB.
`rate_limited`	429	Dosažen limit na přihlašovací údaje (60 rpm) nebo na organizaci (600 rpm).

Hlavičky omezení počtu požadavků

Každá odpověď — úspěšná i chybová — nese stav omezení:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1716461235

X-RateLimit-Limit — limit, který platí pro tento požadavek.
X-RateLimit-Remaining — kolik volání zbývá v aktuálním okně.
X-RateLimit-Reset — unixové časové razítko, kdy se Remaining resetuje.

Při 429 je také nastaveno Retry-After (v sekundách) podle RFC 6585.

Rozsahy omezení

Rozsah	Limit	Okno
Na přihlašovací údaje	60	1 minuta
Na organizaci (napříč všemi přihlašovacími údaji)	600	1 minuta

Umožňuje nárazové požadavky během první sekundy minuty. Po dosažení limitu vrací další požadavky v okně 429.

Strategie opakování

Exponenciální odstup s jitterem pro 429 / 5xx; neopakujte 4xx (kromě 408, 425, 429):

async function withRetry<T>(fn: () => Promise<T>, max = 5): Promise<T> {
  let lastErr: unknown;
  for (let i = 0; i < max; i++) {
    try {
      return await fn();
    } catch (err: any) {
      const status = err?.status;
      if (status >= 400 && status < 500 && ![408, 425, 429].includes(status)) {
        throw err; // not retryable
      }
      const base = status === 429 ? (err.retryAfterMs ?? 1000) : 250 * 2 ** i;
      const jitter = Math.random() * base * 0.2;
      await new Promise((r) => setTimeout(r, base + jitter));
      lastErr = err;
    }
  }
  throw lastErr;
}

SDK to interně implementují u 429 + 5xx; pokud chcete opakování řešit sami, nastavte v možnostech SDK retries: 0.

Korelace chyb

Každá odpověď nese hlavičku X-Request-Id (UUID). Uveďte ji v jakémkoli tiketu podpory — z tohoto id samotného dokážeme získat kompletní stopu požadavku.

Co dál

Autentizace — rotace přihlašovacích údajů, pokud vidíte 401
Stránkování + idempotence — vzory, které se prolínají s opakováním