Common Errors & Fixes
A quick-reference cheat sheet for the messages you're most likely to see.
"Session not found"
You tried to use a command or API endpoint with a session ID that doesn't exist on your account anymore.
Fix: Reconnect the session from the dashboard. The session may have been removed because of inactivity or a manual disconnect.
"Device was unlinked" (WhatsApp)
WhatsApp removed BotWave from your linked devices, usually because:
- You manually unlinked it
- Your phone has been offline for more than 14 days
- You used WhatsApp Web in a way that conflicted with the linked device
Fix:
- On your phone: WhatsApp → Settings → Linked Devices — confirm BotWave is gone
- In the dashboard, click Connect WhatsApp again and re-scan
"401 Unauthorized" (API)
Your API key is missing, mistyped, or revoked.
Fix: Generate a new key in Settings → API Keys and update your integration.
"429 Too Many Requests"
You're hitting the rate limit for your plan.
Fix: Throttle your requests, batch where possible, or upgrade. See API & Webhooks for the limits.
"Bot is not an admin" (Telegram)
Your Telegram bot can't moderate because it's not an admin in the group.
Fix: Promote the bot — group settings → Administrators → Add Administrator → select your bot → grant at least "Delete messages", "Ban users", and "Pin messages".
"QR code expired"
QR codes are short-lived (≈60s) so they can't be intercepted.
Fix: Click Refresh QR. Have your phone open to the Linked Devices screen so you can scan immediately.
"AI provider error"
Your configured AI provider rejected the request. Common causes: invalid key, expired key, exhausted quota, content policy violation.
Fix:
- Settings → AI Provider → Test key
- If the key is fine, check the provider dashboard for quota / billing alerts
- Try a different model if the current one is being rate-limited