Troubleshooting
This guide covers the most common issues you may encounter when using the Floopy gateway, along with solutions and debugging strategies.
Error Codes
Section titled “Error Codes”When a request fails, the gateway returns a structured error response with an HTTP status code and an error code. Use this table to diagnose and resolve issues.
| HTTP Status | Error Code | Meaning | How to Fix |
|---|---|---|---|
| 400 | BAD_REQUEST | Malformed request body or invalid parameters | Check JSON syntax, required fields (model, messages) |
| 400 | PROMPT_THREAT_DETECTED | LLM firewall blocked the prompt | Review prompt content, adjust firewall threshold, or disable with floopy-llm-security-enabled: false |
| 401 | INVALID_API_KEY | API key is missing, invalid, or revoked | Check Authorization header, verify key in Settings > API Keys |
| 403 | FORBIDDEN | Key lacks permission for this operation | Check API key permissions in Settings |
| 403 | SUBSCRIPTION_EXPIRED | Plan has expired | Renew subscription in Settings > Billing |
| 429 | RATE_LIMIT_EXCEEDED | Too many requests | Wait for Retry-After header duration. Check rate limits in Settings > API Keys |
| 429 | USAGE_LIMIT_EXCEEDED | Token or cost limit reached | Increase limits or wait for reset |
| 429 | MONTHLY_LIMIT_EXCEEDED | Monthly request quota exhausted | Upgrade plan or enable overage billing |
| 502 | PROVIDER_ERROR | Upstream LLM provider returned an error | Check Floopy-Provider header, try different model, configure fallbacks |
| 504 | GATEWAY_TIMEOUT | Provider didn’t respond in time | Increase timeout, configure fallbacks to faster providers |
Debugging Tips
Section titled “Debugging Tips”- Check response headers:
Floopy-ProviderandFloopy-Modeltell you which provider handled the request. - Use the Requests page: every request is logged with full details — click a request to see spans, headers, and error body.
- Test in Playground: isolate prompt issues by testing in the dashboard Playground.
- Enable tracing: distributed tracing shows the full pipeline (auth → cache → firewall → routing → provider).
Common Issues
Section titled “Common Issues”My request works with OpenAI directly but fails through Floopy
Section titled “My request works with OpenAI directly but fails through Floopy”- Check that the provider is configured in Settings > Providers.
- Verify the model name matches exactly (Floopy uses it to resolve the provider).
- Check if the request uses features not supported by the provider (e.g.,
response_formatwith some providers).
I’m getting cache hits but don’t want them
Section titled “I’m getting cache hits but don’t want them”- Send
Floopy-Cache-Enabled: falseheader to bypass cache. - Or disable caching at the API key level in Settings.
My prompt variables aren’t being replaced
Section titled “My prompt variables aren’t being replaced”- Ensure you’re sending the
floopy-prompt-idheader. - Pass variable values in the
inputsfield of the request body (not in message content). - Variable names must match exactly:
{{name}}in template needs"name"in inputs.
Rate limiting is too aggressive
Section titled “Rate limiting is too aggressive”- Default org rate limit is 10,000 RPM. Check Settings > API Keys for per-key limits.
- Use
floopy-ratelimit-policyheader for per-request overrides.
Fallback isn’t working
Section titled “Fallback isn’t working”- Ensure multiple providers are configured.
- Check circuit breaker state at
GET /health/providers. - Verify routing rule has fallback strategy with multiple providers.
Does Floopy add latency?
Section titled “Does Floopy add latency?”The gateway adds ~2–5ms overhead. Cache hits return in under 10ms. The LLM firewall now routes through the BackendRouter (configured via FIREWALL_MODEL); latency depends on the chosen backend, with the Qdrant verdict cache short-circuiting repeat unsafe prompts.
Is my data stored?
Section titled “Is my data stored?”Request/response logs are stored in ClickHouse for observability. Cache stores responses in Redis/Qdrant. You control retention in Settings. API keys to providers are encrypted at rest.
Can I use Floopy with non-chat endpoints?
Section titled “Can I use Floopy with non-chat endpoints?”Currently only POST /v1/chat/completions is supported. Embeddings, images, and other endpoints are planned.
What happens if Floopy goes down?
Section titled “What happens if Floopy goes down?”If the gateway is unreachable, your SDK will get a connection error. We recommend configuring your application with a direct-to-provider fallback for critical paths.