Troubleshooting
Este guia cobre os problemas mais comuns que você pode encontrar ao usar o gateway Floopy, junto com soluções e estratégias de depuração.
Códigos de Erro
Quando uma requisição falha, o gateway retorna uma resposta de erro estruturada com um código de status HTTP e um código de erro. Use esta tabela para diagnosticar e resolver problemas.
| HTTP Status | Error Code | Significado | Como Resolver |
|---|---|---|---|
| 400 | BAD_REQUEST | Corpo da requisição malformado ou parâmetros inválidos | Verifique a sintaxe JSON, campos obrigatórios (model, messages) |
| 400 | PROMPT_THREAT_DETECTED | O firewall de LLM bloqueou o prompt | Revise o conteúdo do prompt, ajuste o limite do firewall ou desative com floopy-llm-security-enabled: false |
| 401 | INVALID_API_KEY | API key ausente, inválida ou revogada | Verifique o header Authorization, confirme a key em Settings > API Keys |
| 403 | FORBIDDEN | A key não tem permissão para esta operação | Verifique as permissões da API key em Settings |
| 403 | SUBSCRIPTION_EXPIRED | O plano expirou | Renove a assinatura em Settings > Billing |
| 429 | RATE_LIMIT_EXCEEDED | Muitas requisições | Aguarde a duração do header Retry-After. Verifique os rate limits em Settings > API Keys |
| 429 | USAGE_LIMIT_EXCEEDED | Limite de tokens ou custo atingido | Aumente os limites ou aguarde o reset |
| 429 | MONTHLY_LIMIT_EXCEEDED | Cota mensal de requisições esgotada | Faça upgrade do plano ou habilite cobrança de excedente |
| 502 | PROVIDER_ERROR | O provider de LLM upstream retornou um erro | Verifique o header Floopy-Provider, tente outro modelo, configure fallbacks |
| 504 | GATEWAY_TIMEOUT | O provider não respondeu a tempo | Aumente o timeout, configure fallbacks para providers mais rápidos |
Dicas de Depuração
- Verifique os headers de resposta:
Floopy-ProvidereFloopy-Modelinformam qual provider atendeu a requisição. - Use a página de Requests: cada requisição é registrada com detalhes completos — clique em uma requisição para ver spans, headers e corpo do erro.
- Teste no Playground: isole problemas de prompt testando no Playground do dashboard.
- Habilite tracing: o tracing distribuído mostra o pipeline completo (auth -> cache -> firewall -> routing -> provider).
Problemas Comuns
Minha requisição funciona direto com a OpenAI mas falha pelo Floopy
- Verifique se o provider está configurado em Settings > Providers.
- Confirme que o nome do modelo corresponde exatamente (o Floopy usa isso para resolver o provider).
- Verifique se a requisição usa recursos não suportados pelo provider (ex.:
response_formatcom alguns providers).
Estou recebendo cache hits mas não quero
- Envie o header
Floopy-Cache-Enabled: falsepara ignorar o cache. - Ou desative o cache no nível da API key em Settings.
Minhas variáveis de prompt não estão sendo substituídas
- Certifique-se de que está enviando o header
floopy-prompt-id. - Passe os valores das variáveis no campo
inputsdo corpo da requisição (não no conteúdo da mensagem). - Os nomes das variáveis devem corresponder exatamente:
{{name}}no template precisa de"name"em inputs.
O rate limiting está muito agressivo
- O rate limit padrão da organização é 10.000 RPM. Verifique Settings > API Keys para limites por key.
- Use o header
floopy-ratelimit-policypara substituições por requisição.
O fallback não está funcionando
- Certifique-se de que múltiplos providers estão configurados.
- Verifique o estado do circuit breaker em
GET /health/providers. - Confirme que a regra de roteamento tem uma estratégia de fallback com múltiplos providers.
FAQ
O Floopy adiciona latência?
O gateway adiciona ~2–5ms de overhead. Cache hits retornam em menos de 10ms. O firewall LLM agora roteia pelo BackendRouter (configurado via FIREWALL_MODEL); a latência depende do backend escolhido, com o cache de vereditos no Qdrant evitando chamadas repetidas para prompts inseguros conhecidos.
Meus dados são armazenados?
Logs de request/response são armazenados no ClickHouse para observabilidade. O cache armazena respostas no Redis/Qdrant. Você controla a retenção em Settings. API keys dos providers são criptografadas em repouso.
Posso usar o Floopy com endpoints que não são de chat?
Atualmente apenas POST /v1/chat/completions é suportado. Embeddings, images e outros endpoints estão planejados.
O que acontece se o Floopy cair?
Se o gateway estiver inacessível, seu SDK receberá um erro de conexão. Recomendamos configurar sua aplicação com um fallback direto para o provider em caminhos críticos.