# Facturación y errores de OpenAPI Comprende el saldo de la plataforma, los cargos por solicitud y resultado, la facturación por página y los reintentos seguros. Esta página aplica a `/api/v1/data/*`, las APIs exclusivas de la plataforma OpenAPI de Felo. Las llamadas usan **saldo de la plataforma**, un saldo de crédito de servicio denominado en USD. No consumen créditos Felo Pro. Las [API de Felo](https://openapi.felo.ai/es/docs/api-reference/felo-apis.md) anteriores bajo `/v2` usan créditos Pro. ## Leer los precios actuales ```bash curl -sS https://openapi.felo.ai/api/v1/data/prices ``` Este endpoint público no requiere clave. Haz coincidir sus entradas por ID de operación y lee la tarifa y la unidad de facturación actuales; no supongas que todas las operaciones cuestan lo mismo ni fijes una tarifa de un ejemplo en tu aplicación. | ID de operación | Unidad de facturación | |---|---| | `web.search`, `web.read`, `chat` | Solicitud | | `x.user.info`, `x.user.search`, `x.user.tweets`, `x.tweet.search`, `x.tweet.replies` | Resultado devuelto | | `ppt.generate` | Página generada | | `ppt.export` | Solicitud de exportación | | `ppt.generate.status`, `ppt.generate.historical`, `ppt.export.status`, `ppt.delete` | Sin nuevo cargo | Una consulta de estado gratuita no hace gratuita la generación o la exportación subyacentes. Para X, la paginación y los registros anidados devueltos pueden aumentar el uso facturable. ## Saldo y reservas Antes de la ejecución, el servicio puede reservar saldo suficiente para la operación. El trabajo correcto se liquida contra esa reserva; el fallo confirmado la libera. Para tareas asíncronas, devolver un ID no significa que la facturación ya sea definitiva. La facturación por página de PPT reserva diez páginas al crear. La generación exitosa liquida la salida real y libera los fondos no utilizados. La generación y la exportación son cargos separados. Consulta el [flujo de trabajo de PPT](https://openapi.felo.ai/es/docs/data-api/guides/felo-ppt.md) para el comportamiento de exportaciones repetidas. Si la ejecución o la liquidación son inciertas, una reserva puede permanecer pendiente mientras el servicio la concilia. No consideres cada timeout o 5xx como prueba de que no ocurrió ningún trabajo o de que una solicitud repetida sea gratuita. Revisa tu saldo disponible y el uso en [Consola de facturación](https://openapi.felo.ai/console/billing). Para orientación sobre recarga a nivel de cuenta, consulta [Facturación y créditos](https://openapi.felo.ai/es/docs/faq/billing-and-credits.md). ## Consultar el uso del monedero a través de la API Los propietarios de la cuenta pueden inspeccionar los registros de llamadas del monedero usando un **token de inicio de sesión de Felo**. Esta credencial es distinta de la clave API usada para llamadas a Data API; no la sustituyas por `FELO_API_KEY`. ```bash curl -sS 'https://openapi.felo.ai/api/wallet/usage?call_type=data' \ -H 'Authorization: Bearer YOUR_FELO_LOGIN_TOKEN' ``` Los registros están bajo `data.items`; `call_type=data` filtra las llamadas de capacidad. Compara el uso con los precios actuales de la cuenta. Leer registros no envía otra tarea de generación. La Consola de facturación sigue disponible para revisión y recargas de la cuenta. ## Leer errores de forma defensiva Comprueba primero el estado HTTP. Los errores pueden usar cualquiera de estas formas; los valores siguientes son ilustrativos: ```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"} ``` Lee `error.code` / `error.message` cuando estén presentes, o si no `code` / `message`. Conserva `request_id` cuando se devuelva. Las respuestas exitosas varían según la operación; no las fuerces a todas al mismo envoltorio de error o `data`. ## Decide qué hacer después | Estado HTTP | Causa común | Siguiente paso | |---|---|---| | 400 | Parámetro faltante o inválido | Corrige la solicitud antes de reintentar | | 401 | Clave faltante, inválida, revocada o caducada | Revisa la clave y el encabezado de autenticación | | 402 | Saldo de la plataforma insuficiente | Comprueba el saldo disponible y las reservas pendientes; recarga si es necesario | | 404 | Recurso faltante o inaccesible para esta cuenta | Revisa el ID y la cuenta creadora | | 409 | La operación entra en conflicto con el estado actual de la tarea, o la ejecución no está confirmada | Lee el código de error y consulta la tarea existente; no la dupliques de inmediato | | 410 | Recurso caducado o eliminado | Usa un archivo guardado; crea una nueva tarea solo si es necesario | | 429 | Límite de frecuencia o cuota de clave API superados | Inspecciona la información de reinicio; reduce la velocidad o espera al restablecimiento de la cuota | | 502 / 503 / 504 | Fallo upstream, de disponibilidad, de timeout o de liquidación | Comprueba si el trabajo ya existe antes de reintentar una operación pagada | `execution_unconfirmed` (409) y `billing_settlement_pending` (503) requieren especial cuidado: no reenvíes de inmediato el trabajo pagado. Consulta las tareas conocidas o contacta con soporte con el ID de la solicitud. Un estado HTTP exitoso con un resultado vacío es distinto de una respuesta de error. ## Reintentar sin crear trabajo duplicado - Para consultas de solo lectura de tareas y estado de exportación, usa un backoff limitado y respeta `Retry-After` cuando esté presente. - Para una solicitud de creación fallida con un `task_id` guardado, consulta esa tarea antes de crear otra. - Si la conexión falló antes de que recibieras un ID, el resultado puede ser desconocido. No asumas que reenviar deduplicará la solicitud. - Para 429, distingue un límite de frecuencia corto de una ventana de cuota de clave API; reintentar repetidamente no puede restablecer la cuota. - Detén los reintentos después de una fecha límite configurada y muestra un error accionable al llamador. Para soporte, proporciona el endpoint, la hora aproximada, el estado HTTP y el ID de la solicitud. Nunca incluyas la clave API completa.