fix(google): improve error message for model/API mismatch in Realtime API

[cdutr]

Summary

This PR improves error messages when users accidentally configure a Gemini API model with VertexAI (or vice versa) in the Google Realtime plugin. Currently, users receive a cryptic WebSocket 1008 policy violation error that doesn't explain the root cause.

Problem

When using the Google Realtime plugin with incorrect model/API combinations:

• Users get a confusing error: websockets.exceptions.ConnectionClosedError: received 1008 (policy violation)
• The error doesn't explain that the model name doesn't match the API being used
• Users spend significant time debugging WebSocket configurations instead of fixing the simple model name issue
• This is a common pain point (see issue Audio quality issue with sip outbound call #4026 and related reports)

Example Scenario

A user tries to use VertexAI with a Gemini API model name:

model = google.realtime.RealtimeModel(
    model="gemini-2.5-flash-native-audio-preview-09-2025",  # Gemini API model
    vertexai=True,  # But using VertexAI
)

Current error:

websockets.exceptions.ConnectionClosedError: received 1008 (policy violation)

After this fix:

Failed to connect to Gemini Live

Hint: Model 'gemini-2.5-flash-native-audio-preview-09-2025' appears to be a Gemini API model,
but VertexAI is enabled. VertexAI requires different model names (prefixed with 'gemini-live-').
Try using model='gemini-live-2.5-flash-preview-native-audio-09-2025' instead.

Solution

Added a helper function _get_model_mismatch_hint() that:

1. Detects WebSocket 1008 policy violation errors
2. Checks if the model name pattern matches the API being used
3. Returns a helpful hint with the suggested correct model name
4. Only activates on actual 1008 errors (non-intrusive approach)

The hint is appended to both:

• Logger error messages
• Raised APIConnectionError exceptions

This provides immediate, actionable feedback without blocking any valid configurations or making assumptions about future model naming patterns.

Testing

• Verified hint appears for Gemini API models + VertexAI
• Verified hint appears for VertexAI models + Gemini API
• Verified no hint for correct configurations
• Verified no hint for non-1008 errors
• Verified correct model suggestions for September and December 2025 models

Fixes livekit/livekit#4026

Summary by CodeRabbit

• Bug Fixes
  • Improved error messages for connection failures with contextual hints regarding model and API configuration
  • Error logs now suggest configuration adjustments to resolve detected model/API mismatches

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[CLAassistant]

All committers have signed the CLA.

[coderabbitai]

📝 Walkthrough

Walkthrough

A new helper function _get_model_mismatch_hint() was added to detect WebSocket 1008 errors indicating model/API mismatches and generate contextual hints. The main task exception handling now invokes this helper to augment error messages with suggested alternative model names based on configuration.

Changes

Cohort / File(s)	Summary
Error hint detection and augmentation livekit-plugins/livekit-plugins-google/livekit/plugins/google/realtime/realtime_api.py	Added _get_model_mismatch_hint() helper function to detect WebSocket 1008 policy violations and suggest corrective model names. Enhanced exception handling in _main_task() to log and propagate augmented error messages containing hints when model/API mismatches are detected.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 A mismatch of models caused quite a fright,
But now we detect it and set things right!
With hints that suggest which path to take,
Vertex and Gemini peace now make! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: improving error messages for model/API mismatch detection in the Google Realtime API.
Linked Issues check	✅ Passed	The PR implements the core objective from issue #4026 by adding error detection and contextual hints for model/API mismatches, reducing debugging time for users encountering WebSocket 1008 errors.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to addressing the model/API mismatch issue; no unrelated modifications were introduced outside the linked objectives.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7fe642d and 03d9750.

📒 Files selected for processing (1)

• livekit-plugins/livekit-plugins-google/livekit/plugins/google/realtime/realtime_api.py

🧰 Additional context used

📓 Path-based instructions (1)

**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

**/*.py: Format code with ruff
Run ruff linter and auto-fix issues
Run mypy type checker in strict mode
Maintain line length of 100 characters maximum
Ensure Python 3.9+ compatibility
Use Google-style docstrings

Files:

• livekit-plugins/livekit-plugins-google/livekit/plugins/google/realtime/realtime_api.py

🧬 Code graph analysis (1)

livekit-plugins/livekit-plugins-google/livekit/plugins/google/realtime/realtime_api.py (9)

livekit-plugins/livekit-plugins-google/livekit/plugins/google/llm.py (1)

• model (227-228)

livekit-plugins/livekit-plugins-openai/livekit/plugins/openai/realtime/realtime_model.py (2)

• model (363-364)
• session (605-608)

livekit-agents/livekit/agents/llm/llm.py (1)

• model (99-108)

livekit-plugins/livekit-plugins-aws/livekit/plugins/aws/llm.py (1)

• model (118-119)

livekit-plugins/livekit-plugins-anthropic/livekit/plugins/anthropic/llm.py (1)

• model (118-119)

livekit-plugins/livekit-plugins-mistralai/livekit/plugins/mistralai/llm.py (1)

• model (61-62)

livekit-plugins/livekit-plugins-openai/livekit/plugins/openai/llm.py (1)

• model (171-172)

livekit-plugins/livekit-plugins-ultravox/livekit/plugins/ultravox/realtime/realtime_model.py (2)

• model (214-215)
• session (228-238)

livekit-plugins/livekit-plugins-xai/livekit/plugins/xai/realtime/realtime_model.py (1)

• session (112-115)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: type-check (3.9)
• GitHub Check: type-check (3.13)
• GitHub Check: unit-tests

🔇 Additional comments (2)

livekit-plugins/livekit-plugins-google/livekit/plugins/google/realtime/realtime_api.py (2)

808-830: Nice improvement to surface actionable hints in errors.

Appending the mismatch hint to both logs and raised APIConnectionError messages makes the 1008 failure far more actionable without changing retry semantics.

---

63-94: The code is already compliant with the coding guidelines. LiveAPIModels is a Literal type alias, not a custom class—meaning it's fully compatible with the str type expected by _get_model_mismatch_hint. The function's parameter is correctly typed as str, and self._opts.model (which has a property returning str) is passed safely.

All f-string lines are within the 100-character limit (lines 74, 75, 89, and 90 are 87, 75, 90, and 46 characters respectively). No ruff E501 violations exist, and no defensive normalization or line wrapping is necessary.

Likely an incorrect or invalid review comment.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}