# OpenAPI: білінг і помилки

Розумійте баланс платформи, списання за запит і результат, білінг сторінок і безпечні повтори.

Ця сторінка стосується `/api/v1/data/*`, ексклюзивних API платформи Felo OpenAPI. Виклики використовують **баланс платформи**, сервісний кредитний баланс у USD. Вони не витрачають кредити Felo Pro. Старі [Felo APIs](https://openapi.felo.ai/uk/docs/api-reference/felo-apis.md) під `/v2` використовують Pro credits.

## Переглянути поточні ціни

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

Ця публічна кінцева точка не потребує ключа. Зіставляйте її записи за ID операції та читайте поточну ставку й одиницю білінгу; не припускайте, що всі операції коштують однаково, і не переносіть ставку з прикладу у свій застосунок.

| ID операції | Одиниця білінгу |
|---|---|
| `web.search`, `web.read`, `chat` | Запит |
| `x.user.info`, `x.user.search`, `x.user.tweets`, `x.tweet.search`, `x.tweet.replies` | Повернутий результат |
| `ppt.generate` | Згенерована сторінка |
| `ppt.export` | Запит експорту |
| `ppt.generate.status`, `ppt.generate.historical`, `ppt.export.status`, `ppt.delete` | Без нового списання |

Безкоштовний запит статусу не робить базову генерацію чи експорт безкоштовними. Для X пагінація та вкладені повернуті записи можуть збільшувати обсяг, що підлягає оплаті.

## Баланс і резервування

Перед виконанням сервіс може зарезервувати достатній баланс для операції. Успішна робота проводиться проти цього резерву; підтверджений збій звільняє його. Для асинхронних завдань повернення ID не означає, що білінг уже остаточний.

За ціною сторінок PPT під час створення резервуються десять сторінок. Успішна генерація проводить фактичний вихід і звільняє невикористані кошти. Генерація та експорт є окремими списаннями. Дивіться [робочий процес PPT](https://openapi.felo.ai/uk/docs/data-api/guides/felo-ppt.md) щодо поведінки повторного експорту.

Якщо виконання або розрахунок викликає сумнів, резерв може залишатися в очікуванні, поки сервіс його узгоджує. Не вважайте кожен тайм-аут або 5xx доказом того, що робота не виконувалася або що повторний запит безкоштовний.

Переглядайте доступний баланс і використання в [Console Billing](https://openapi.felo.ai/console/billing). Для рекомендацій щодо поповнення на рівні облікового запису дивіться [Білінг і кредити](https://openapi.felo.ai/uk/docs/faq/billing-and-credits.md).

## Перевірити використання гаманця через API

Власники облікового запису можуть переглядати записи викликів гаманця, використовуючи **токен входу Felo**. Ця облікова інформація відрізняється від API Key, що використовується для викликів Data API; не підставляйте `FELO_API_KEY`.

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

Записи знаходяться в `data.items`; `call_type=data` фільтрує виклики можливостей. Порівнюйте використання з поточними цінами облікового запису. Читання записів не надсилає ще одне завдання генерації. Console Billing залишається доступним для перегляду облікового запису та поповнень.

## Обробляйте помилки захищено

Спершу перевірте HTTP-статус. Помилки можуть використовувати одну з цих форм; значення нижче є ілюстративними:

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

Читатйте `error.code` / `error.message`, якщо вони присутні, інакше `code` / `message`. Зберігайте `request_id`, якщо він повернутий. Успішні відповіді різняться залежно від операції; не примушуйте їх усі до однієї й тієї самої помилки або оболонки `data`.

## Вирішіть, що робити далі

| HTTP-статус | Типова причина | Наступний крок |
|---|---|---|
| 400 | Відсутній або недійсний параметр | Виправте запит перед повтором |
| 401 | Відсутній, недійсний, відкликаний або прострочений ключ | Перевірте ключ і заголовок автентифікації |
| 402 | Недостатній баланс платформи | Перевірте доступний баланс і резерви; поповніть за потреби |
| 404 | Ресурс відсутній або недоступний для цього облікового запису | Перевірте ID і обліковий запис, що створив ресурс |
| 409 | Операція конфліктує з поточним станом завдання або виконання не підтверджено | Прочитайте код помилки й запитайте наявне завдання; не дублюйте його одразу |
| 410 | Термін дії ресурсу закінчився або його видалено | Використайте збережений файл; створюйте нове завдання лише за потреби |
| 429 | Перевищено ліміт частоти або квоту API key | Перевірте інформацію про скидання; зменште швидкість або зачекайте скидання квоти |
| 502 / 503 / 504 | Upstream, недоступність, тайм-аут або збій розрахунку | Перед повтором платної операції перевірте, чи робота вже існує |

`execution_unconfirmed` (409) і `billing_settlement_pending` (503) потребують особливої уваги: не надсилайте платну роботу повторно негайно. Запросіть відомі завдання або зверніться до підтримки з request ID. Успішний HTTP-статус із порожнім результатом відрізняється від відповіді з помилкою.

## Повторюйте без створення дубльованої роботи

- Для запитів до завдань лише для читання та статусу експорту використовуйте обмежений backoff і дотримуйтеся `Retry-After`, коли він присутній.
- Для невдалого запиту створення зі збереженим `task_id` спочатку запитайте це завдання, перш ніж створювати ще одне.
- Якщо з’єднання не вдалося до отримання ID, результат може бути невідомим. Не припускайте, що повторна відправка дедуплікує запит.
- Для 429 розрізняйте короткий ліміт частоти та вікно квоти API key; повторні спроби не скидають квоту.
- Зупиняйте повтори після налаштованого дедлайну та показуйте викликачу дієву помилку.

Для підтримки надайте кінцеву точку, приблизний час, HTTP-статус і request ID. Ніколи не включайте повний API key.