# Cobrança e erros da OpenAPI

Entenda o saldo da plataforma, cobranças por solicitação e por resultado, cobrança por página e novas tentativas seguras.

Esta página se aplica a `/api/v1/data/*`, as APIs exclusivas da plataforma Felo OpenAPI. As chamadas usam **saldo da plataforma**, um saldo de crédito de serviço denominado em USD. Elas não consomem créditos Pro da Felo. As [APIs Felo](https://openapi.felo.ai/pt-BR/docs/api-reference/felo-apis.md) mais antigas em `/v2` usam créditos Pro.

## Leia os preços atuais

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

Este endpoint público não requer chave. Faça a correspondência de suas entradas por ID de operação e leia a tarifa e a unidade de cobrança atuais; não presuma que toda operação custa o mesmo nem fixe uma tarifa de um exemplo em seu aplicativo.

| ID da operação | Unidade de cobrança |
|---|---|
| `web.search`, `web.read`, `chat` | Solicitação |
| `x.user.info`, `x.user.search`, `x.user.tweets`, `x.tweet.search`, `x.tweet.replies` | Resultado retornado |
| `ppt.generate` | Página gerada |
| `ppt.export` | Solicitação de exportação |
| `ppt.generate.status`, `ppt.generate.historical`, `ppt.export.status`, `ppt.delete` | Sem nova cobrança |

Uma consulta de status gratuita não torna a geração ou exportação subjacente gratuita. Para X, paginação e registros aninhados retornados podem aumentar o uso cobrável.

## Saldo e reservas

Antes da execução, o serviço pode reservar saldo suficiente para a operação. O trabalho concluído é acertado contra essa reserva; falha confirmada a libera. Para tarefas assíncronas, retornar um ID não significa que a cobrança já é final.

O preço por página de PPT reserva dez páginas na criação. A geração bem-sucedida acerta a saída real e libera os fundos não utilizados. Geração e exportação são cobranças separadas. Veja o [fluxo de PPT](https://openapi.felo.ai/pt-BR/docs/data-api/guides/felo-ppt.md) para o comportamento de exportação repetida.

Se a execução ou o acerto forem incertos, uma reserva pode permanecer pendente enquanto o serviço a concilia. Não trate todo timeout ou 5xx como prova de que nada aconteceu ou de que uma solicitação repetida é gratuita.

Revise seu saldo disponível e uso em [Cobrança do Console](https://openapi.felo.ai/console/billing). Para orientação de recarga no nível da conta, consulte [Cobrança e Créditos](https://openapi.felo.ai/pt-BR/docs/faq/billing-and-credits.md).

## Consulte o uso da carteira pela API

Os proprietários da conta podem inspecionar registros de chamadas da carteira usando um **token de login da Felo**. Essa credencial é diferente da API Key usada para chamadas do Data API; não a substitua por `FELO_API_KEY`.

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

Os registros ficam em `data.items`; `call_type=data` filtra chamadas de capacidade. Compare o uso com os preços atuais da conta. Ler registros não envia outra tarefa de geração. A Cobrança do Console continua disponível para revisão da conta e recargas.

## Leia erros de forma defensiva

Verifique primeiro o status HTTP. Os erros podem usar uma destas formas; os valores abaixo são 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"}
```

Leia `error.code` / `error.message` quando presentes, caso contrário `code` / `message`. Preserve `request_id` quando retornado. As respostas bem-sucedidas variam conforme a operação; não as force todas para o mesmo envelope de erro ou `data`.

## Decida o que fazer a seguir

| Status HTTP | Causa comum | Próximo passo |
|---|---|---|
| 400 | Parâmetro ausente ou inválido | Corrija a solicitação antes de tentar novamente |
| 401 | Chave ausente, inválida, revogada ou expirada | Verifique a chave e o cabeçalho de autenticação |
| 402 | Saldo da plataforma insuficiente | Verifique o saldo disponível e as reservas pendentes; recarregue se necessário |
| 404 | Recurso ausente ou inacessível para esta conta | Verifique o ID e a conta criadora |
| 409 | A operação conflita com o estado atual da tarefa, ou a execução não foi confirmada | Leia o código de erro e consulte a tarefa existente; não a duplique imediatamente |
| 410 | Recurso expirado ou excluído | Use um arquivo salvo; crie uma nova tarefa apenas se necessário |
| 429 | Limite de taxa ou cota da API Key excedidos | Inspecione as informações de reinicialização; reduza a velocidade ou aguarde a redefinição da cota |
| 502 / 503 / 504 | Falha upstream, de disponibilidade, timeout ou de acerto | Verifique se o trabalho já existe antes de repetir uma operação paga |

`execution_unconfirmed` (409) e `billing_settlement_pending` (503) exigem cuidado especial: não reenvie imediatamente o trabalho pago. Consulte tarefas conhecidas ou contate o suporte com o ID da solicitação. Um status HTTP bem-sucedido com resultado vazio é diferente de uma resposta de erro.

## Refaça sem criar trabalho duplicado

- Para consultas somente de leitura de tarefa e status de exportação, use backoff limitado e respeite `Retry-After` quando presente.
- Para uma solicitação de criação com falha e um `task_id` salvo, consulte essa tarefa antes de criar outra.
- Se a conexão falhou antes de você receber um ID, o resultado pode ser desconhecido. Não presuma que reenviar deduplicará a solicitação.
- Para 429, diferencie um limite de taxa curto de uma janela de cota da API Key; repetir indefinidamente não redefinirá a cota.
- Pare as repetições após um prazo final configurado e mostre um erro acionável ao chamador.

Para suporte, informe o endpoint, o horário aproximado, o status HTTP e o ID da solicitação. Nunca inclua a chave da API completa.