# Биллинг и ошибки OpenAPI

Поймите баланс платформы, списания за запрос и результат, тарификацию страниц и безопасные повторы.

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

## Читайте текущие цены

```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/ru/docs/data-api/guides/felo-ppt.md) для поведения при повторном экспорте.

Если выполнение или списание неясны, резерв может оставаться в ожидании, пока сервис сверяет данные. Не считайте каждый тайм-аут или 5xx доказательством того, что работа не была выполнена или что повторный запрос бесплатен.

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

## Проверка использования кошелька через API

Владельцы аккаунта могут просматривать записи вызовов кошелька, используя **Felo login token**. Этот учетный данные отличаются от 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 | Ошибка вышестоящего сервиса, доступности, тайм-аута или списания | Проверьте, не существует ли работа уже, перед повтором платной операции |

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

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

- Для только читаемых запросов к задачам и статусу экспорта используйте ограниченный backoff и соблюдайте `Retry-After`, если он есть.
- Для неудачного запроса создания с сохраненным `task_id` сначала запросите эту задачу, прежде чем создавать новую.
- Если соединение оборвалось до получения ID, результат может быть неизвестен. Не предполагайте, что повторная отправка устранит дубликат.
- Для 429 различайте кратковременный лимит частоты и окно квоты API key; многократные повторные попытки не сбрасывают квоту.
- Останавливайте повторы после заданного дедлайна и показывайте вызывающему сторону действенную ошибку.

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