Troubleshooting

This guide covers the most common issues you may encounter when using the Floopy gateway, along with solutions and debugging strategies.

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

Check response headers: Floopy-Provider and Floopy-Model tell 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

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_format with some providers).

I’m getting cache hits but don’t want them

Send Floopy-Cache-Enabled: false header to bypass cache.
Or disable caching at the API key level in Settings.

My prompt variables aren’t being replaced

Ensure you’re sending the floopy-prompt-id header.
Pass variable values in the inputs field 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

Default org rate limit is 10,000 RPM. Check Settings > API Keys for per-key limits.
Use floopy-ratelimit-policy header for per-request overrides.

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.

FAQ

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?

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?

Currently only POST /v1/chat/completions is supported. Embeddings, images, and other endpoints are planned.

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.