# OpenAPI rozliczenia i błędy

Zrozum saldo platformy, opłaty za żądania i wyniki, rozliczanie stron oraz bezpieczne ponawianie prób.

Ta strona dotyczy `/api/v1/data/*`, czyli wyłącznych dla platformy API OpenAPI Felo. Wywołania korzystają z **salda platformy**, salda kredytów usługowych denominowanego w USD. Nie zużywają kredytów Felo Pro. Starsze [Felo APIs](https://openapi.felo.ai/pl/docs/api-reference/felo-apis.md) pod `/v2` używają kredytów Pro.

## Odczytaj bieżące ceny

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

Ten publiczny punkt końcowy nie wymaga klucza. Dopasowuj jego wpisy po identyfikatorze operacji i odczytuj bieżącą stawkę oraz jednostkę rozliczeniową; nie zakładaj, że każda operacja kosztuje tyle samo, ani nie przenoś stawki z przykładu do swojej aplikacji.

| ID operacji | Jednostka rozliczeniowa |
|---|---|
| `web.search`, `web.read`, `chat` | Żądanie |
| `x.user.info`, `x.user.search`, `x.user.tweets`, `x.tweet.search`, `x.tweet.replies` | Zwrócony wynik |
| `ppt.generate` | Wygenerowana strona |
| `ppt.export` | Żądanie eksportu |
| `ppt.generate.status`, `ppt.generate.historical`, `ppt.export.status`, `ppt.delete` | Brak nowej opłaty |

Bezpłatne zapytanie o status nie czyni darmowym samego generowania ani eksportu. W przypadku X stronicowanie i zagnieżdżone zwrócone rekordy mogą zwiększyć rozliczane użycie.

## Saldo i rezerwacje

Przed wykonaniem usługa może zarezerwować wystarczające saldo dla operacji. Udane wykonanie rozlicza się względem tej rezerwacji; potwierdzona porażka ją zwalnia. W przypadku zadań asynchronicznych zwrócenie identyfikatora nie oznacza, że rozliczenie jest już ostateczne.

Cennik stron PPT rezerwuje dziesięć stron przy utworzeniu. Udane generowanie rozlicza rzeczywisty wynik i zwalnia niewykorzystane środki. Generowanie i eksport to osobne opłaty. Zobacz [przepływ pracy PPT](https://openapi.felo.ai/pl/docs/data-api/guides/felo-ppt.md) w sprawie zachowania przy ponownym eksporcie.

Jeśli wykonanie lub rozliczenie jest niepewne, rezerwacja może pozostać w stanie oczekującym, podczas gdy usługa ją uzgadnia. Nie traktuj każdego timeoutu ani 5xx jako dowodu, że nic się nie wydarzyło lub że powtórzone żądanie jest darmowe.

Sprawdź dostępne saldo i użycie w [Console Billing](https://openapi.felo.ai/console/billing). W kwestiach doładowania na poziomie konta zobacz [Billing and Credits](https://openapi.felo.ai/pl/docs/faq/billing-and-credits.md).

## Sprawdzaj użycie portfela przez API

Właściciele kont mogą sprawdzać rekordy wywołań portfela, używając **tokena logowania Felo**. Ten poświadczenie różni się od API Key używanego do wywołań Data API; nie zastępuj go `FELO_API_KEY`.

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

Rekordy znajdują się w `data.items`; `call_type=data` filtruje wywołania możliwości. Porównaj użycie z aktualnymi cenami konta. Odczyt rekordów nie wysyła kolejnego zadania generowania. Console Billing pozostaje dostępne do przeglądu konta i doładowań.

## Czytaj błędy defensywnie

Najpierw sprawdź status HTTP. Błędy mogą przyjmować jedną z tych postaci; poniższe wartości mają charakter poglądowy:

```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"}
```

Odczytaj `error.code` / `error.message`, gdy są obecne, w przeciwnym razie `code` / `message`. Zachowaj `request_id`, jeśli został zwrócony. Udane odpowiedzi różnią się w zależności od operacji; nie wymuszaj ich wszystkich do tego samego błędu lub otoczki `data`.

## Zdecyduj, co zrobić dalej

| Status HTTP | Typowa przyczyna | Następny krok |
|---|---|---|
| 400 | Brakujący lub nieprawidłowy parametr | Popraw żądanie przed ponowną próbą |
| 401 | Brakujący, nieprawidłowy, odwołany lub wygasły klucz | Sprawdź klucz i nagłówek uwierzytelniania |
| 402 | Niewystarczające saldo platformy | Sprawdź dostępne saldo i oczekujące rezerwacje; w razie potrzeby doładuj |
| 404 | Zasób brakujący lub niedostępny dla tego konta | Sprawdź identyfikator i konto tworzące |
| 409 | Operacja koliduje z bieżącym stanem zadania lub wykonanie nie jest potwierdzone | Odczytaj kod błędu i sprawdź istniejące zadanie; nie duplikuj go od razu |
| 410 | Zasób wygasł lub został usunięty | Użyj zapisanego pliku; utwórz nowe zadanie tylko jeśli to konieczne |
| 429 | Przekroczono limit żądań lub limit quota klucza API | Sprawdź informacje o odnowieniu; zwolnij tempo lub poczekaj na reset quota |
| 502 / 503 / 504 | Awaria nadrzędna, dostępności, limitu czasu lub rozliczenia | Sprawdź, czy praca już istnieje, zanim ponownie spróbujesz operacji płatnej |

`execution_unconfirmed` (409) i `billing_settlement_pending` (503) wymagają szczególnej ostrożności: nie wysyłaj natychmiast ponownie płatnej pracy. Sprawdź znane zadania lub skontaktuj się ze wsparciem, podając identyfikator żądania. Udany status HTTP z pustym wynikiem to co innego niż odpowiedź błędu.

## Ponawiaj bez tworzenia duplikatów pracy

- W przypadku tylko do odczytu zapytań o status zadania i status eksportu używaj ograniczonego backoffu i respektuj `Retry-After`, gdy jest obecny.
- W przypadku nieudanego żądania utworzenia z zapisanym `task_id` sprawdź to zadanie przed utworzeniem kolejnego.
- Jeśli połączenie nie powiodło się zanim otrzymałeś identyfikator, wynik może być nieznany. Nie zakładaj, że ponowne wysłanie zduplikuje żądanie w sposób deduplikowany.
- W przypadku 429 odróżnij krótki limit szybkości od okna quota klucza API; wielokrotne ponawianie nie zresetuje quota.
- Zatrzymaj ponawianie po skonfigurowanym terminie i pokaż wywołującemu działający komunikat o błędzie.

Do wsparcia podaj punkt końcowy, przybliżony czas, status HTTP i identyfikator żądania. Nigdy nie podawaj pełnego klucza API.