Error Handling
This page covers HTTP status codes, media errors, stream errors, and common troubleshooting scenarios for the RAVATAR API.
HTTP Status Codes
These HTTP errors can occur across all API endpoints:
| Status | Name | Description | Recommended Handling |
|---|---|---|---|
| 200 | OK | Request successful | Process response normally |
| 402 | Payment Required | Subscription or payment issue | Show upgrade/payment prompt to user |
| 403 | Forbidden | JWT token expired or invalid | Refresh token via POST /jwt and retry request (see Token Refresh) |
| 503 | Service Unavailable | All AI assistants busy | Show "Please try again later" message |
| 504 | Gateway Timeout | Connection timeout | Retry with exponential backoff |
Media Errors
These errors may occur when accessing microphone or camera:
| Error Code | Description | Recommended Handling |
|---|---|---|
permission_denied | User denied microphone permission | Show permission request dialog with instructions |
no_specified_media_found | Requested media device not found | Show "No microphone found" message |
media_in_use | Media device used by another app | Show "Microphone in use" message |
invalid_media_constraints | Audio constraints not supported | Fall back to default constraints |
no_constraints | No media constraints specified | Use default audio constraints |
recorder_error | MediaRecorder error | Restart recording or show error |
media_aborted | Recording was aborted | Allow user to retry |
Stream Errors
These errors may occur during Live Mode streaming:
| Error | Message | Description | Recommended Handling |
|---|---|---|---|
| Stream Error | "Something went wrong" | Generic stream error | End session and prompt to reconnect |
| Timeout | "Connection timeout" | Stream connection timed out | Retry connection |
| Busy | "All AI assistants are busy at the moment" | No available streaming slots | Show busy message, offer retry later |
| Expired | "Session expired" | Live session ended server-side | Clear LicenseId, prompt to start new session |
Troubleshooting
Failed to get JWT token
Cause: Invalid API URL or network issue.
Solution:
- Verify your API URL is correct (
https://chat.rvtr.ai) - Check your internet connection
- Enable debug logging to see detailed error messages
Failed to load connection
Cause: JWT token expired or invalid.
Solution:
- Obtain a new JWT token via
POST /jwt(see Authentication) - Ensure you received a valid JWT successfully before loading connection data
WebSocket connection fails
Cause: Invalid JWT token or WebSocket URL.
Solution:
- Verify the WebSocket URL is
wss://chat.rvtr.ai/ws/chat?token=YOUR_TOKEN - Ensure the JWT token is valid (refresh if needed)
- Check browser console for WebSocket errors
- See Reconnection Logic for automatic retry implementation
Payment required error (402)
Cause: Account has insufficient balance or payment issue.
Solution: Check your RAVATAR account balance and payment status in the dashboard.
Messages not sending
Cause: WebSocket not connected or missing required fields.
Solution:
- Ensure WebSocket connection is established
- Verify avatar and language are selected from the configuration response
- Check browser console for errors
- Confirm all required message fields are present (see Chat Mode or Live Mode)
PixelStreaming iframe shows a black screen
Cause: The PixelStreaming page is blocking iframe embeds, or there is a mixed content issue.
Solution:
- Open the streaming URL in a new browser tab. If it works there but not in the iframe, check your browser DevTools Console for
X-Frame-Optionsorframe-ancestorserrors. This requires a server-side configuration change. - If your application is served over HTTPS, ensure the
streamingUrlis also HTTPS. Mixed content is blocked by modern browsers.
Enable debug mode
To see detailed logging of all API and WebSocket events:
- Set
VITE_DEBUG_LOGS=truein your environment configuration - Restart the development server
- Open browser console (F12)
- All HTTP requests, WebSocket connection events, message sending/receiving, and error details will be logged
Audio Format Comparison
| Property | Standard (Blob) | Gemini Native (PCM) |
|---|---|---|
| Use Case | Chat Mode | Live Mode (Gemini API) |
| Format | WAV / WebM | Raw PCM |
| Sample Rate | 16 kHz | 16 kHz |
| Bit Depth | Varies | 16-bit signed integer |
| Channels | Mono | Mono |
| Byte Order | N/A | Little-endian |
| Processing | MediaRecorder API | AudioWorklet / raw capture |
| Buffer Size | Continuous | 4,096 samples |
| Transmission Field | file_base64_data | audio_base64_pcm |
| Encoding | Base64 | Base64 |
Glossary
| Term | Definition |
|---|---|
| Avatar | A virtual AI assistant with a visual representation (video/animated) that responds to user messages. |
| Chat Mode | Standard asynchronous messaging mode where avatar responses are pre-rendered and delivered as video/audio files. |
| JWT (JSON Web Token) | A secure token used for API authentication, containing encoded user and session information. |
| LicenseId | A unique identifier for an active Live Mode session, required for all real-time streaming operations. |
| Live Mode | Real-time interactive mode with streaming avatar responses via PixelStreaming technology. |
| PCM (Pulse-Code Modulation) | Raw, uncompressed audio format used for real-time audio streaming in Live Mode. |
| PixelStreaming | Unreal Engine technology for streaming real-time rendered content to browsers and mobile devices. |
| Push-to-Talk | Audio input mode where users manually start/stop recording, as opposed to automatic Voice Activity Detection. |
| Session | A unique identifier for a user's conversation context, obtained from the /connection endpoint. |
| VAD (Voice Activity Detection) | Automatic detection of speech in audio input, used to determine when users start/stop speaking. |
| WebSocket | A protocol for bidirectional, real-time communication between client and server. |