Troubleshooting

Common Issues

API Key Problems

Error: 'API error: 401' or 'Invalid API key'

Cause: Your OpenRouter API key is invalid, expired, or incorrectly formatted.Solutions:

Verify your API key

Go to OpenRouter Keys
Check if your key is active and not expired
Copy the key again (make sure no extra spaces)

Update in PolyChat-AI

Open Settings (Ctrl+, or Cmd+,)
Paste the new key in the “Clé API OpenRouter” field
Click “Sauvegarder”

Test the connection

Send a test message to verify the key works

API keys starting with sk-or-v1- are the correct format. If yours doesn’t match, it may be invalid.

Error: 'API error: 402' or 'Insufficient credits'

Cause: Your OpenRouter account has insufficient credits or hasn’t been funded.Solutions:

Visit OpenRouter Credits to add funds
Check your current balance in the OpenRouter dashboard
Consider using free models (filter by “Free” in model selection)

Free model alternatives:

openrouter/free - Access to free models
Look for models with “Free” badge in Settings

Settings won't save API key

Cause: Browser localStorage issues or JavaScript errors.Solutions:

Check Browser Storage
Clear Cache
Browser Compatibility

Open DevTools (F12)
Go to “Application” → “Local Storage”
Find the polychat-settings entry
Verify it updates when you save

Try clearing browser cache and reloading
Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)

Connection & Network Issues

Error: 'Failed to fetch AI response' or network timeout

Cause: Network connectivity issues or OpenRouter API downtime.Diagnostic steps:

# Test OpenRouter API directly
curl -I https://openrouter.ai/api/v1/models

Solutions:

Check your internet connection

Verify you’re online and can access other websites

Check OpenRouter status

Visit OpenRouter Status or check their Discord

Try a different network

Corporate firewalls may block OpenRouter. Try:

Mobile hotspot
VPN
Different WiFi network

Check for CORS issues

Open DevTools Console (F12) and look for CORS errors. If present, this is an OpenRouter API issue.

Slow response times

Cause: Model overload, network latency, or complex prompts.Solutions:

Switch models

Faster alternatives:

google/gemini-3-flash (very fast)
deepseek/deepseek-v3.2 (good speed/quality)
Any model with “flash” in the name

Enable streaming

Streaming responses feel faster by showing results as they arrive. This should be enabled by default.

Simplify prompts

Shorter, clearer prompts typically get faster responses.

Check Usage Dashboard

Press Ctrl+U to compare response times across models you’ve used.

Error: 'API error: 429' - Rate limit exceeded

Cause: You’ve sent too many requests in a short time period.Solutions:

Wait: Rate limits reset after a short period (usually 1 minute)
Reduce request frequency: Add a small delay between messages
Upgrade account: Higher OpenRouter tiers have higher rate limits
Check if you’re making duplicate requests: Debug with DevTools Network tab

If you’re rate limited on free models, try switching to a paid model which may have different limits.

Model & Response Issues

Model not available or deprecated

Cause: The selected model has been removed or renamed by the provider.Solutions:

Open Settings

Press Ctrl+, (or Cmd+,)

Search for updated models

In the “Modèle par défaut” section:

Look for the same provider (e.g., “anthropic”, “openai”)
Find a newer version (higher version number)
Check the “created” date to find recent models

Select and save

Click the new model and save settings

Example: If anthropic/claude-3-opus is unavailable, try anthropic/claude-4.5-sonnet instead.

Poor quality responses or hallucinations

Cause: Model limitations, unclear prompts, or inappropriate model selection.Solutions:

Improve Your Prompt
Try Better Models
Use System Prompts
Multi-Model Comparison

Be specific and detailed
Provide context and examples
Use system prompts for consistent behavior
Break complex tasks into steps

Higher-quality models (though more expensive):

anthropic/claude-4.5-sonnet
openai/gpt-5.2
google/gemini-3-flash

Set a system prompt in Settings:

You are a helpful assistant. Provide accurate, 
well-researched answers. If you're unsure, 
say so rather than guessing.

Response cut off or incomplete

Cause: Token limit reached or streaming interruption.Solutions:

Check model context length:
- Open Settings and view “Ctx” column
- Models with higher context (e.g., 200k) can handle longer responses

Ask for continuation:

Please continue from where you left off.

Simplify your request: Break into smaller questions
Streaming issue: If streaming was interrupted:
- Check your network connection
- Try sending the message again
- See code reference: src/services/openRouter.ts:144-189

Image generation not working

Cause: Wrong model selected or model doesn’t support image generation.Solutions:

Verify model supports images

Only certain models can generate images. Check the model ID contains:

gemini-2.5-flash-image
gpt-4o
claude-3.5-sonnet or claude-3.7-sonnet

See src/services/openRouter.ts:538-551 for the complete list.

Use dedicated image models

The app provides getImageModels() to fetch image-capable models. These are filtered to show only models with text+image->text+image modality.

Check error message

If you see “Le modèle X ne supporte pas la génération d’images”, switch to a supported model.

Image generation uses the generateImageReliable() function which automatically retries with fallback models. See src/services/openRouter.ts:734-824

UI & Display Issues

Usage Dashboard shows no data

Cause: No messages sent yet, or localStorage was cleared.Diagnostic:

Check browser DevTools:
- Open DevTools (F12)
- Application → Local Storage
- Find polychat-usage-stats

Verify data structure:

{
  "totalConversations": 0,
  "totalMessages": 0,
  "totalUserMessages": 0,
  "totalAssistantMessages": 0,
  "avgResponseTimeMs": 0,
  "perModel": {},
  "lastUpdated": "2025-01-01T00:00:00.000Z"
}

Solutions:

Send a test message to start tracking
Check that tracking functions are called (see src/hooks/useUsageStats.ts:26-90)
If lastUpdated is old, stats may have been reset

Theme or colors not applying

Cause: CSS not loaded or theme setting not persisted.Solutions:

Check Settings

Open Settings (Ctrl+,)
Go to “Apparence” section
Manually select theme again

Verify DOM attributes

Open DevTools Elements tab and check:

<html data-theme="dark" data-accent="violet">

Clear CSS cache

Hard reload: Ctrl+Shift+R or Cmd+Shift+R

Theme changes are applied via:

document.documentElement.setAttribute('data-theme', newTheme);
document.body.className = `theme-${newTheme}`;

See src/components/Settings/SettingsModalModern.tsx:65-68

Settings modal won't open

Model list not loading in Settings

Cause: Failed to fetch models from OpenRouter API.Diagnostic:Open DevTools Network tab and check for:

Request: https://openrouter.ai/api/v1/models
Status: Should be 200 OK

Solutions:

Check network connectivity
Verify no CORS errors in console
Try reloading the page
Check if OpenRouter API is down

The app fetches models via getTopWeeklyModels() and getImageModels() in src/services/openRouter.ts

Debugging Tools

Browser DevTools

Use these DevTools features for debugging:

Console
Network
Application

Purpose: View JavaScript errors and logsHow to use:

Press F12 → Console tab
Look for red error messages
Check for warnings about API calls

Common errors:

Failed to fetch: Network issue
Uncaught TypeError: JavaScript error
CORS error: API access issue

Purpose: Monitor API requestsHow to use:

Press F12 → Network tab
Reload page and send a message
Look for requests to openrouter.ai

What to check:

Status code (should be 200)
Request headers (verify API key)
Response body (actual API response)
Timing (identify slow requests)

Purpose: Inspect localStorage dataHow to use:

Press F12 → Application tab
Local Storage → select your domain
Find these keys:
- polychat-settings
- polychat-usage-stats

What to check:

API key is stored correctly
Settings persist after reload
Usage stats update after messages

Source Code References

Key files to check when debugging:

Issue Type	File Location	Line Reference
API calls	`src/services/openRouter.ts`	Lines 5-97 (fetch), 102-191 (streaming)
Settings persistence	`src/hooks/useSettings.ts`	Check persist middleware
Usage tracking	`src/hooks/useUsageStats.ts`	Lines 26-90 (tracking functions)
Model list	`src/hooks/useModels.ts`	Check model fetching
UI components	`src/components/Settings/`	Settings modal and dashboard

Testing API Directly

Test OpenRouter API outside the app:

# Test with curl
curl https://openrouter.ai/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "anthropic/claude-4.5-sonnet",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Expected response:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      }
    }
  ]
}

If this fails, the issue is with your API key or OpenRouter account, not PolyChat-AI.

Advanced Debugging

Enable Verbose Logging

Add console logs to track execution:

// In src/services/openRouter.ts
export const fetchAIResponse = async (...) => {
  console.log('API Request:', { messages, model });
  
  const response = await fetch(API_URL, ...);
  console.log('API Response Status:', response.status);
  
  const data = await response.json();
  console.log('API Response Data:', data);
  
  return data.choices[0].message.content;
};

Monitor State Changes

For Zustand stores, add middleware:

import { create } from 'zustand';
import { devtools } from 'zustand/middleware';

export const useSettings = create(
  devtools(
    persist(
      (set) => ({
        // ... your state
      }),
      { name: 'polychat-settings' }
    ),
    { name: 'Settings Store' }
  )
);

Then install Redux DevTools to inspect state.

Performance Profiling

Open Performance tab

Press F12 → Performance

Record interaction

Click record, send a message, stop recording

Analyze

Look for:

Long tasks (> 50ms)
Network waterfalls
Memory leaks

Getting Help

Before Asking for Help

Gather this information:

Resources

OpenRouter Discord

Get help with API and model issues

OpenRouter Docs

Official API documentation

GitHub Issues

Report bugs in PolyChat-AI (check with your team for the repo URL)

Check Status

Verify OpenRouter API uptime

Error Code Reference

Code	Meaning	Typical Cause
400	Bad Request	Malformed API request
401	Unauthorized	Invalid API key
402	Payment Required	Insufficient credits
403	Forbidden	API key lacks permissions
429	Rate Limited	Too many requests
500	Server Error	OpenRouter API issue
502	Bad Gateway	OpenRouter upstream issue
503	Service Unavailable	OpenRouter maintenance

Reset & Recovery

Reset All Settings

This will erase all your settings, API key, and preferences. Usage statistics will be preserved.

Open DevTools

Press F12 → Application → Local Storage

Delete settings key

Find and delete polychat-settings

Reload

Refresh the page to start with default settings

Reset Usage Statistics

Open Usage Dashboard

Press Ctrl+U (or Cmd+U)

Find reset button

Look for “Reset Statistics” or similar option

Confirm

Confirm the reset action

Or manually via DevTools:

Open DevTools → Application → Local Storage
Delete polychat-usage-stats
Reload the page

Complete Reset

To completely reset PolyChat-AI:

// Run in DevTools Console
localStorage.clear();
location.reload();

This deletes ALL local data and reloads the app with defaults.

Get Started

Core Features

Guides

Advanced

Common Issues

API Key Problems

Connection & Network Issues

Switch models

Enable streaming

Simplify prompts

Check Usage Dashboard

Model & Response Issues

UI & Display Issues

Debugging Tools

Browser DevTools

Source Code References

Testing API Directly

Advanced Debugging

Enable Verbose Logging

Monitor State Changes

Performance Profiling

Getting Help

Before Asking for Help

Resources

OpenRouter Discord

OpenRouter Docs

GitHub Issues

Check Status

Error Code Reference

Reset & Recovery

Reset All Settings

Reset Usage Statistics

Complete Reset

Build docs developers (and LLMs) love

Get Started

Core Features

Guides

Advanced

​Common Issues

​API Key Problems

​Connection & Network Issues

Switch models

Enable streaming

Simplify prompts

Check Usage Dashboard

​Model & Response Issues

​UI & Display Issues

​Debugging Tools

​Browser DevTools

​Source Code References

​Testing API Directly

​Advanced Debugging

​Enable Verbose Logging

​Monitor State Changes

​Performance Profiling

​Getting Help

​Before Asking for Help

​Resources

OpenRouter Discord

OpenRouter Docs

GitHub Issues

Check Status

​Error Code Reference

​Reset & Recovery

​Reset All Settings

​Reset Usage Statistics

​Complete Reset

Build docs developers (and LLMs) love

Common Issues

API Key Problems

Connection & Network Issues

Model & Response Issues

UI & Display Issues

Debugging Tools

Browser DevTools

Source Code References

Testing API Directly

Advanced Debugging

Enable Verbose Logging

Monitor State Changes

Performance Profiling

Getting Help

Before Asking for Help

Resources

Error Code Reference

Reset & Recovery

Reset All Settings

Reset Usage Statistics

Complete Reset