Even the best AI systems occasionally misbehave. This guide helps you quickly diagnose and fix the most common issues with your Chat.co chatbot.
Quick Diagnosis
Before diving deep, try these quick fixes: refresh the page, clear browser cache, check your internet connection, and verify your API key hasn't expired.
1. Bot Not Responding
If your chatbot isn't responding at all, here's how to diagnose the issue.
Symptoms
- Messages show "loading" indefinitely
- No response after sending a message
- Widget appears but doesn't accept input
- API calls return no response
Common Causes & Solutions
Invalid or Expired API Key
Your API key may be invalid, expired, or not associated with a chatbot.
Fix:
- 1. Go to Settings → API Keys in your dashboard
- 2. Verify your key hasn't expired
- 3. Ensure the key is assigned to a chatbot
- 4. Generate a new key if needed
Rate Limit Exceeded
You may have exceeded your message credits or hit API rate limits.
Fix:
- 1. Check your usage in Settings → Billing
- 2. Wait for rate limits to reset (15 minutes)
- 3. Upgrade your plan if consistently hitting limits
Chatbot Frozen
After a plan downgrade, excess chatbots may be frozen.
Fix:
- 1. Go to your dashboard and check for frozen bots
- 2. Upgrade your plan to unfreeze, or
- 3. Delete unused bots to free up slots
API Error Codes
| Error Code | Meaning | Action |
|---|---|---|
| INVALID_API_KEY | Key missing or invalid | Check/regenerate API key |
| CHATBOT_ACCESS_DENIED | Key not linked to bot | Assign key to chatbot |
| MESSAGE_LIMIT_EXCEEDED | Monthly credits used | Upgrade plan or wait for reset |
| CHATBOT_FROZEN | Bot inactive due to downgrade | Upgrade or free up bot slots |
2. Incorrect or Hallucinated Answers
AI "hallucinations" occur when the model generates plausible-sounding but incorrect information. Here's how to minimize them.
Symptoms
- Responses contain factually incorrect information
- Bot invents details not in your documents
- Answers don't match your knowledge base
- Confident-sounding but wrong responses
Root Causes & Solutions
If your documents don't cover a topic, the AI may try to fill gaps with its general knowledge, which may be wrong.
Fix: Upload comprehensive documents that cover all topics your bot should know about. Enable "I don't know" responses for topics outside your KB.
Multiple documents with contradictory information confuse the AI.
Fix: Audit your knowledge base for outdated documents. Remove duplicates and ensure information is consistent across sources.
The wrong documents are being retrieved for the user's question.
Fix: Increase topK to retrieve more context, or adjust similarityThreshold to filter out irrelevant matches.
Pro Tip: Enable citations in your chatbot settings. When users can see the source of information, they can verify accuracy and trust builds naturally.
3. Missing Citations
Citations are crucial for trust. If your bot isn't providing sources, here's how to fix it.
Symptoms
- Responses have no citation links
- Citations array is empty in API response
- "Show sources" button doesn't appear
Common Causes & Solutions
Citations Disabled in Settings
Check Appearance → Advanced → Show Citations is enabled.
No Relevant Documents Retrieved
If the similarity threshold is too high, no documents may be retrieved.
similarityThreshold from 0.8 to 0.6-0.7.Document Processing Incomplete
Documents still being processed won't appear in citations.
Expert Bot Configuration Issues
For expert bots using Bedrock Agents, citations require proper agent configuration.
4. Slow Response Times
If your chatbot takes too long to respond, users may abandon the conversation.
Symptoms
- Responses take more than 10 seconds
- First message is much slower than subsequent ones
- Intermittent slowdowns
Optimization Strategies
Streaming is Enabled by Default
Chat.co uses streaming responses by default, so users see text as it's generated. If responses still feel slow, this is likely due to model or knowledge base factors below.
Choose a Faster Model
Claude 3.5 Haiku is faster than Sonnet for simple queries.
Reduce Retrieved Context
Lower topK from 10 to 5 to reduce context processing time.
Optimize Knowledge Base
Remove redundant documents. Smaller, focused KBs perform faster.
Expected Response Times
| Scenario | Expected Time |
|---|---|
| Simple question, streaming enabled | First token: <1s |
| Complex question, non-streaming | 3-8 seconds |
| First message (cold start) | +2-3 seconds |
5. Document Ingestion Failures
When documents fail to process, they won't be available for your chatbot to reference.
Symptoms
- Red X or error icon next to document in Sources
- "Processing failed" status
- Document not appearing in source count
Common Causes & Solutions
File Too Large
Maximum file size is 50MB. Split large documents into smaller files.
Scanned PDF (Image-Only)
PDFs containing only images need OCR processing. Try running OCR before upload or use a different format.
Password-Protected File
Remove password protection before uploading.
Corrupted File
Try opening the file locally to verify it's not corrupted. Re-export if needed.
Unsupported Format
Supported formats: PDF, DOCX, DOC, TXT, MD, HTML. Convert other formats first.
Tip: If a document repeatedly fails, try converting it to plain text (.txt) format. This bypasses most parsing issues.
6. Embed Not Loading
If the chat widget isn't appearing on your website, check these common issues.
Symptoms
- No chat bubble visible on website
- Widget frame appears but is blank
- Console shows JavaScript errors
Troubleshooting Steps
Check Embed Code Placement
The embed script should be placed just before the closing </body> tag.
Verify Chatbot ID
Ensure data-chatbot-id matches your actual chatbot ID from the dashboard.
Check CSP Headers
Content Security Policy may block the widget. Add widget.chat.co to your allowed sources.
Check Browser Console
Open DevTools (F12) and check the Console tab for JavaScript errors.
Test Chatbot Visibility
Make sure the chatbot is set to "Public" in settings if embedding on a public website.
Correct Embed Code
<!-- Place before </body> --> <script src="https://widget.chat.co/embed.js" data-chatbot-id="YOUR_CHATBOT_ID" async ></script>
7. When to Contact Support
If you've tried the above solutions and still have issues, our support team is here to help.
Contact Support When:
- Issues persist after following troubleshooting steps
- You encounter error codes not listed above
- You need help with enterprise configurations
- You suspect a platform-wide issue
- You need custom integrations or features
How to Get Help
Email Support
support@chat.co
Response within 24 hours
Contact Form
chat.co/contact-us
Detailed issue reporting
Include in Your Support Request
- Your chatbot ID and account email
- Steps to reproduce the issue
- Error messages or codes you're seeing
- Screenshots or screen recordings if applicable
- Browser and device information
We're Here to Help
Our team is committed to your success. Don't hesitate to reach out—we're happy to help you get the most out of Chat.co.