Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(troubleshooting): map a session that is not ready to 400 or 409

Yudhi Armyndharisd13cf6848a89
diff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.md
index 573f68485..a6a8846a0 100644
--- a/docs/12-troubleshooting-faq.md
+++ b/docs/12-troubleshooting-faq.md
@@ -680,13 +680,13 @@ curl -H "X-API-Key: $API_KEY" \
**Common Causes:**
-| Cause | Symptom | Solution |
-| ---------------------- | ---------------------- | --------------------------- |
-| Invalid phone number | 400 error | Format: `[email protected]` |
-| Rate limited | 429 error | Reduce sending rate |
-| Session disconnected | 503 error | Reconnect session |
-| Media too large | 413 error | Compress or reduce size |
-| Number not on WhatsApp | Message fails silently | Verify number first |
+| Cause | Symptom | Solution |
+| -------------------------------- | ---------------------------- | ------------------------------ |
+| Invalid phone number | 400 error | Format: `[email protected]` |
+| Rate limited | 429 error | Reduce sending rate |
+| Session not started or not ready | 400 (`is not active`) or 409 | Start or reconnect the session |
+| Media too large | 413 error | Compress or reduce size |
+| Number not on WhatsApp | Message fails silently | Verify number first |
**Phone Number Validation:**
@@ -1423,17 +1423,17 @@ available_events:
### HTTP Error Codes
-| Code | Meaning | Common Cause | Solution |
-| ---- | ------------------- | ------------------------ | ------------------------- |
-| 400 | Bad Request | Invalid parameters | Check request body/params |
-| 401 | Unauthorized | Missing/invalid API key | Add X-API-Key header |
-| 403 | Forbidden | Insufficient permissions | Check API key permissions |
-| 404 | Not Found | Invalid session/endpoint | Verify session exists |
-| 409 | Conflict | Session already exists | Use different session ID |
-| 413 | Payload Too Large | File too large | Reduce file size |
-| 429 | Too Many Requests | Rate limited | Reduce request rate |
-| 500 | Internal Error | Server error | Check logs |
-| 503 | Service Unavailable | Session disconnected | Reconnect session |
+| Code | Meaning | Common Cause | Solution |
+| ---- | ------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------- |
+| 400 | Bad Request | Invalid parameters, or the session is not started | Check request body/params; start the session |
+| 401 | Unauthorized | Missing/invalid API key | Add X-API-Key header |
+| 403 | Forbidden | Insufficient permissions | Check API key permissions |
+| 404 | Not Found | Invalid session/endpoint | Verify session exists |
+| 409 | Conflict | Session already exists, or the session is not ready (retryable) | Use a different session ID, or wait for `ready` |
+| 413 | Payload Too Large | File too large | Reduce file size |
+| 429 | Too Many Requests | Rate limited | Reduce request rate |
+| 500 | Internal Error | Server error | Check logs |
+| 503 | Service Unavailable | The engine transport died during a read, or a media fetch through the session proxy failed | Retry; restart the session if it persists |
### Error Body Shape