# OpenAPI účtování a chyby

Pochopte zůstatek platformy, poplatky za požadavek a výsledek, účtování za stránku a bezpečné opakování.

Tato stránka se vztahuje na `/api/v1/data/*`, exkluzivní API platformy Felo OpenAPI. Volání používají **zůstatek platformy**, kreditový zůstatek služeb v USD. Nespotřebovávají Felo Pro credits. Starší [Felo APIs](https://openapi.felo.ai/cs/docs/api-reference/felo-apis.md) pod `/v2` používají Pro credits.

## Přečtěte aktuální ceny

```bash
curl -sS https://openapi.felo.ai/api/v1/data/prices
```

Tento veřejný koncový bod nevyžaduje klíč. Položky porovnávejte podle ID operace a čtěte aktuální sazbu a účtovací jednotku; nepředpokládejte, že každá operace stojí stejně, ani nezamrazujte sazbu z příkladu do své aplikace.

| ID operace | Účtovací jednotka |
|---|---|
| `web.search`, `web.read`, `chat` | Požadavek |
| `x.user.info`, `x.user.search`, `x.user.tweets`, `x.tweet.search`, `x.tweet.replies` | Vrácený výsledek |
| `ppt.generate` | Vygenerovaná stránka |
| `ppt.export` | Exportní požadavek |
| `ppt.generate.status`, `ppt.generate.historical`, `ppt.export.status`, `ppt.delete` | Žádný nový poplatek |

Bezplatný dotaz na stav nedělá samotné generování ani export bezplatnými. U X může stránkování a zanořené vrácené záznamy zvýšit zpoplatněné použití.

## Zůstatek a rezervace

Před provedením může služba rezervovat dostatečný zůstatek pro operaci. Úspěšná práce se zúčtuje proti této rezervaci; potvrzené selhání ji uvolní. U asynchronních úloh vrácení ID neznamená, že je účtování už konečné.

Cenotvorba za stránky PPT při vytvoření rezervuje deset stránek. Úspěšné generování zúčtuje skutečný výstup a uvolní nevyužité prostředky. Generování a export jsou samostatné poplatky. Viz [workflow PPT](https://openapi.felo.ai/cs/docs/data-api/guides/felo-ppt.md) pro chování při opakovaném exportu.

Pokud je provedení nebo zúčtování nejisté, může rezervace zůstat čekající, zatímco služba vše vyrovnává. Nepovažujte každý timeout nebo 5xx za důkaz, že se nic nestalo nebo že opakovaný požadavek je zdarma.

Zkontrolujte svůj dostupný zůstatek a využití v [Console Billing](https://openapi.felo.ai/console/billing). Pro pokyny k dobití na úrovni účtu viz [Billing and Credits](https://openapi.felo.ai/cs/docs/faq/billing-and-credits.md).

## Dotazování využití peněženky přes API

Vlastníci účtů mohou kontrolovat záznamy volání peněženky pomocí **Felo login tokenu**. Tato přihlašovací údaje jsou odlišné od API klíče používaného pro volání Data API; nenahrazujte jimi `FELO_API_KEY`.

```bash
curl -sS 'https://openapi.felo.ai/api/wallet/usage?call_type=data' \
  -H 'Authorization: Bearer YOUR_FELO_LOGIN_TOKEN'
```

Záznamy jsou v `data.items`; `call_type=data` filtruje capability calls. Porovnejte využití s aktuálními cenami účtu. Čtení záznamů neposílá další generovací úlohu. Console Billing zůstává k dispozici pro kontrolu účtu a dobití.

## Chyby čtěte defenzivně

Nejprve zkontrolujte HTTP stav. Chyby mohou používat jednu z těchto struktur; níže uvedené hodnoty jsou ilustrativní:

```json
{"error":{"code":"invalid_parameter","message":"Check the request fields"},"request_id":"example-request-id"}
```

```json
{"status":402,"code":"INSUFFICIENT_BALANCE","message":"Insufficient balance","request_id":"example-request-id"}
```

Čtěte `error.code` / `error.message`, pokud jsou přítomny, jinak `code` / `message`. Zachovejte `request_id`, pokud je vrácen. Úspěšné odpovědi se liší podle operace; nenuťte je všechny do stejného chybového nebo `data` obalu.

## Rozhodněte, co dělat dál

| HTTP stav | Běžná příčina | Další krok |
|---|---|---|
| 400 | Chybějící nebo neplatný parametr | Před opakováním opravte požadavek |
| 401 | Chybějící, neplatný, odvolaný nebo vypršelý klíč | Zkontrolujte klíč a autentizační hlavičku |
| 402 | Nedostatečný zůstatek platformy | Zkontrolujte dostupný zůstatek a čekající rezervace; v případě potřeby dobijte |
| 404 | Zdroj chybí nebo je pro tento účet nepřístupný | Zkontrolujte ID a účet, který jej vytvořil |
| 409 | Operace je v konfliktu se stavem aktuální úlohy nebo provedení není potvrzené | Přečtěte chybový kód a dotazujte existující úlohu; nezdvojte ji okamžitě |
| 410 | Zdroj vypršel nebo byl smazán | Použijte uložený soubor; novou úlohu vytvořte jen v případě potřeby |
| 429 | Překročen rate limit nebo kvóta API klíče | Prozkoumejte informace o resetu; zpomalte nebo počkejte na reset kvóty |
| 502 / 503 / 504 | Selhání upstreamu, dostupnosti, timeoutu nebo zúčtování | Před opakováním zpoplatněné operace zkontrolujte, zda práce už neexistuje |

`execution_unconfirmed` (409) a `billing_settlement_pending` (503) vyžadují zvláštní opatrnost: okamžitě zpoplatněnou práci znovu neodesílejte. Dotazujte známé úlohy nebo kontaktujte podporu s request ID. Úspěšný HTTP stav s prázdným výsledkem je něco jiného než chybová odpověď.

## Opakování bez vytvoření duplicitní práce

- Pro dotazy pouze na čtení a stav exportu používejte omezený backoff a respektujte `Retry-After`, pokud je přítomen.
- Pro neúspěšný požadavek na vytvoření s uloženým `task_id` nejprve dotazujte tuto úlohu, než vytvoříte další.
- Pokud spojení selhalo dříve, než jste obdrželi ID, výsledek může být neznámý. Nepředpokládejte, že opětovné odeslání požadavek deduplikuje.
- U 429 rozlišujte krátký rate limit od okna kvóty API klíče; opakované pokusy kvótu neresetují.
- Zastavte opakování po nastaveném termínu a zobrazte volajícímu akční chybu.

Pro podporu uveďte koncový bod, přibližný čas, HTTP stav a request ID. Nikdy neuvádějte celý API klíč.