Průvodci

Chyby, limity a opakování

Čtěte chybové odpovědi a hlavičky limitů rychlosti, opakujte bezpečně a diagnostikujte běžné problémy.

Každé API Felo vrací tělo chyby v JSON se stabilním kódem chyby a ID požadavku. Nejprve přečtěte stav HTTP, potom kód a nakonec zprávu.

Obálka chyby

Současné produkční odpovědi používají stav HTTP jako status:

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid API Key",
  "request_id": "202610221444486982113280416060637185"
}

Pole	Význam
`status`	Stavový kód HTTP, zopakovaný v těle
`code`	Strojově čitelný kód chyby
`message`	Vysvětlení čitelné pro člověka
`request_id`	Neprůhledný identifikátor tohoto požadavku; uvádějte jej v žádostech o podporu

Některé starší příklady endpointů používají status: "error" a jiný řetězec kódu. Větvěte podle stavu HTTP a pole code, nikoli podle přesného znění pole message.

Běžné kódy

HTTP	Kód	Co znamená	Co dělat
400	Validační kód specifický pro endpoint	Parametr chybí nebo je neplatný	Opravte požadavek; neopakujte jej nezměněný
401	`UNAUTHORIZED`	Chybějící, neplatný, expirovaný nebo zrušený API klíč	Odešlete `Authorization: Bearer $FELO_API_KEY`; pokud byl klíč zrušen, rotujte jej
402	`INSUFFICIENT_CREDITS`	Nedostatek kreditů služeb	Dobijte v Console Billing a potom opakujte
404	Specifické pro endpoint	Neznámý model, úloha nebo trasa	Zkontrolujte ID modelu nebo ID úlohy a cestu endpointu
429	`RATE_LIMITED`	Byl překročen limit rychlosti	Počkejte na `Retry-After` a potom opakujte
5xx	`CHAT_FAILED`, `*_FAILED`, `SERVICE_UNAVAILABLE`	Selhání upstreamu nebo služby	Opakujte s rostoucím odstupem; pokud problém přetrvává, kontaktujte podporu

Reference endpointů uvádějí kódy specifické pro daný endpoint. Začněte u chyb Chat API nebo u reference endpointu, který voláte.

Endpointy generování modelů

POST /api/v1/images/generations a POST /api/v1/videos/generations vracejí chyby na úrovni endpointu v obálce OpenAI namísto výše uvedené obálky:

{
  "error": {
    "message": "Model kind does not match this generation endpoint",
    "type": "invalid_request_error",
    "param": null,
    "code": "model_kind_mismatch"
  }
}

ID požadavku je v hlavičce odpovědi X-Request-Id, nikoli v těle. Odmítnutý požadavek nevytvoří úlohu. Jakmile úloha existuje, většina selhání přichází jako koncový stav úlohy v odpovědi 200 namísto chyby HTTP: zkontrolujte status na hodnoty failed nebo interrupted a potom přečtěte error.message. Viz Generování obrázků a Asynchronní úlohy.

ID požadavků

Těla chyb Felo obsahují request_id. Zaznamenejte jej spolu s endpointem, stavem HTTP, kódem chyby, ID modelu a ID úlohy. Nikdy nezaznamenávejte celý API klíč.

Model API také přijímá volitelnou hlavičku požadavku X-Request-Id. Když ji odešlete, je vrácena zpět pro diagnostiku, což vám umožní korelovat vlastní logy s požadavkem. Pokud ji neodešlete, použijte vrácený request_id.

Limity rychlosti

/v2/chat je jediný endpoint Felo s dokumentovanými vynucenými limity rychlosti:

Na API klíč, okno 1 minuty.
Na uživatele, okno 1 minuty.
Na uživatele, okno 1 hodiny.

Uživatelé s aktivním placeným předplatným Felo, včetně podnikových předplatných, jsou z nich vyjmuti a nedostávají žádné hlavičky X-RateLimit-*. Pokud stav předplatného nelze ověřit, limity se stále uplatňují.

Hlavička	Význam
`X-RateLimit-Limit`	Limit nejužší dimenze, která je aktuálně v platnosti
`X-RateLimit-Remaining`	Minimální zbývající kvóta napříč třemi dimenzemi
`X-RateLimit-Reset`	Unixový časový údaj v sekundách, kdy se aktuální okno resetuje
`Retry-After`	U odpovědi 429 doporučené zpoždění v sekundách

Ostatní endpointy /v2/** aktuálně nemají vynucené limity rychlosti. Požadavky na Model API mohou být stále omezeny upstreamovým poskytovatelem, což se může projevit jako 429.

Nezadávejte číselné limity natvrdo. Čtěte hlavičky u každé odpovědi.

Zásady opakování

Situace	Opakovat?
400, 401, 402, 404	Ne. Nejprve opravte požadavek, klíč nebo zůstatek.
429	Ano, po `Retry-After` nebo `X-RateLimit-Reset`.
5xx, časové limity, resetování připojení	Ano, s exponenciálním rostoucím odstupem a jitterem.
Streamovací připojení přerušené uprostřed odpovědi	Opakujte pouze tehdy, pokud vaše aplikace snese duplicitní generování.

Doporučená smyčka:

Opakujte pouze idempotentní nebo bezpečně opakovatelné požadavky.
Používejte exponenciální odstup: začněte kolem 1 sekundy, zdvojnásobujte jej, zastropujte na 30 sekund.
Přidejte náhodný jitter, aby klienti neopakovali v souběhu.
Po malém počtu pokusů skončete a zobrazte chybu.
Při 429 respektujte Retry-After namísto vlastního plánu.

Pořadí ladění

Zkontrolujte, že klíč existuje a není zrušený.
Zavolejte GET /api/v1/models se stejným klíčem a potvrďte ověření.
Odešlete nejmenší platný požadavek na cílový endpoint.
Přidávejte streamování, nástroje nebo velké vstupy po jednom.
U asynchronní práce zkontrolujte stav úlohy před opětovným odesláním.