Perguntas frequentes

Solução de problemas

Resolva problemas de autenticação, modelos, streaming, tarefas e limites de taxa com uma checklist baseada em sintomas.

Comece pelo sintoma e siga a correção. A maioria das falhas vem da URL base, da chave, do ID do modelo ou do saldo.

Tabela por sintoma

Sintoma	Causa provável	Correção
401 `UNAUTHORIZED`	Chave ausente, errada, revogada ou não enviada	Envie `Authorization: Bearer $FELO_API_KEY`; crie uma nova chave se ela foi revogada
402 `INSUFFICIENT_CREDITS`	O saldo não cobre a chamada	Recarregue em Console Billing
404 em todas as requisições	A URL base inclui um caminho que o endpoint já acrescenta	Use `https://openapi.felo.ai/api/v1` para clientes OpenAI e `https://openapi.felo.ai/api` para clientes Anthropic
404 em um modelo	O ID do modelo não é público, ou o endpoint não o serve	Verifique o ID do modelo na página de modelos e na documentação do endpoint
Erro 400 de `model` ou `max_tokens`	Campo obrigatório ausente, ou o modelo não aceita o formato da requisição	Adicione `max_tokens` para Messages; remova campos sem suporte
429	Limite de requisições, ou limite de um provedor upstream	Leia `Retry-After`; consulte Erros, limites e novas tentativas
5xx	Falha do upstream ou do serviço	Tente novamente com backoff; inclua o `request_id` se persistir
O stream conecta mas não envia nada	Um proxy está buferizando a resposta, ou o parser de eventos espera o formato errado	Leia o stream de forma incremental; desative o buffering de resposta no seu proxy
A tarefa nunca termina	Endpoint de consulta errado, ou um status terminal não foi tratado	Consulte o endpoint de status da própria tarefa e pare nos valores terminais
Chamadas de ferramentas são ignoradas	O modelo não anuncia esse recurso	Verifique `supported_parameters` no catálogo
A Data API retorna 404	O prefixo `/v1/beta` foi adicionado duas vezes	Use o caminho exatamente como está escrito na referência

Autenticação

Uma chave revogada retorna uma mensagem que informa o prefixo da chave:

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "API Key has been revoked (keyPrefix=...)"
}

Lista de verificação:

O cabeçalho é Authorization: Bearer <key> para a Model API e as Felo APIs.
A Data API também aceita X-API-Key: <key>.
A chave não está entre aspas e não tem quebra de linha sobrando de uma variável de ambiente copiada.
O ambiente implantado realmente tem a variável definida; uma chave que funciona localmente pode estar faltando em produção.
A chave não foi excluída nem rotacionada. Uma chave excluída ou rotacionada não pode ser exibida de novo; crie uma nova.

Consulte Autenticação para ver a criação de chaves e os limites.

Armadilhas de URL base

Cliente	URL base correta
SDK da OpenAI	`https://openapi.felo.ai/api/v1`
SDK da Anthropic	`https://openapi.felo.ai/api`
Endpoint de modelo direto	`https://openapi.felo.ai/api/v1/chat/completions`, `/responses` ou `/messages`
Data API	`https://openapi.felo.ai/v1/beta`
APIs `/v2` da Felo	`https://openapi.felo.ai/v2`

Dois erros comuns:

Adicionar /chat/completions a uma URL base que o SDK já estende.
Definir a URL base da Anthropic como https://openapi.felo.ai/api/v1. O SDK acrescenta /v1/messages, então a requisição fica /api/v1/v1/messages.

Problemas de ID de modelo

Os IDs de modelo são os IDs públicos do catálogo, não os nomes internos do provedor upstream nem um nome de exibição.

Procure o ID na página de modelos ou em GET /api/v1/models.
Confirme que o modelo oferece suporte ao protocolo que você está chamando (supported_protocols).
Se você fixou um canal, confirme que aquele canal está publicado e executável para o modelo. Um canal indisponível não é um fallback.

Consulte Canais e roteamento de provedores.

Problemas de streaming

Defina stream: true no corpo da requisição, não como parâmetro de consulta.
Leia o corpo da resposta como stream. Esperar a resposta completa anula o streaming.
Alguns proxies e plataformas serverless buferizam respostas. Desative o buffering na rota que faz proxy da requisição.
O Chat Completions faz stream de choices[0].delta, não de choices[0].message. O conteúdo final chega ao longo de muitos chunks.
Um stream pode terminar sem um evento terminal limpo se a conexão cair. Trate uma conexão interrompida como uma resposta incompleta.

Problemas de tarefas assíncronas

Consulte o endpoint de status que pertence à família da tarefa. Os fluxos Felo usam GET /v2/tasks/{task_id}/status; as tarefas de vídeo e de imagem de modelos usam os próprios endpoints de geração.
Pare em todos os status terminais, incluindo falhas e expirações, não apenas no sucesso.
Callbacks de vídeo e de imagem são ignorados no momento. Não espere por um webhook.
Uma URL de resultado pode ter validade curta. Solicite uma URL nova no endpoint de status se um download expirar.
Verifique a tarefa antes de reenviar. Reenviar uma tarefa em execução cria uma duplicata, e ambas são cobradas.

Consulte Tarefas assíncronas.

Problemas da Data API

Mantenha o caminho e o método exatos da referência da Data API.
Os corpos de requisição são específicos do fornecedor. Um campo que funciona em um fornecedor não tem garantia de funcionar em outro.
Um erro de provedor pode chegar dentro de uma resposta 4xx com uma mensagem específica do provedor. Registre request_id e o corpo da resposta.

Lembretes de segurança

Nunca coloque uma chave de API em código de navegador, no pacote de um app mobile ou em um repositório público. Mantenha-a em um servidor e faça proxy das requisições.
Não registre a chave completa. Registre um prefixo se precisar identificá-la.
Rotacione uma chave imediatamente se ela pode ter vazado.

Antes de falar com o suporte

Reúna:

O endpoint e o método HTTP.
O status HTTP, code e request_id.
O ID do modelo ou o ID da tarefa.
O timestamp com fuso horário.
Um corpo de requisição mínimo com os segredos removidos.

Envie isso ao suporte com o e-mail da conta. Não inclua a chave de API completa.