{"record":{"id":"f60f0b3b66d50f3c","repo":"openai/openai-python","slug":"websocket-error-event-f60f0b","errorCode":null,"errorMessage":"WebSocket error: {event}","messagePattern":"WebSocket error: (.+?)","errorType":"exception","errorClass":"OpenAIError","httpStatus":null,"severity":"error","filePath":"src/openai/resources/realtime/realtime.py","lineNumber":537,"sourceCode":"    async def dispatch_events(self) -> None:\n        \"\"\"Run the event loop, dispatching received events to registered handlers.\n\n        Blocks until the connection is closed. This is the push-based\n        alternative to iterating with ``async for event in connection``.\n\n        If an ``\"error\"`` event arrives and no handler is registered for\n        ``\"error\"`` or ``\"event\"``, an ``OpenAIError`` is raised.\n        \"\"\"\n        import asyncio\n\n        async for event in self:\n            event_type = event.type\n            specific = self._event_handler_registry.get_handlers(event_type)\n            generic = self._event_handler_registry.get_handlers(\"event\")\n\n            if event_type == \"error\" and not specific and not generic:\n                if isinstance(event, RealtimeErrorEvent):\n                    raise OpenAIError(f\"WebSocket error: {event}\")\n\n            for handler in specific:\n                result = handler(event)\n                if asyncio.iscoroutine(result):\n                    await result\n\n            for handler in generic:\n                result = handler(event)\n                if asyncio.iscoroutine(result):\n                    await result\n\n\nclass AsyncRealtimeConnectionManager:\n    \"\"\"\n    Context manager over a `AsyncRealtimeConnection` that is returned by `realtime.connect()`\n\n    This context manager ensures that the connection will be closed when it exits.\n","sourceCodeStart":519,"sourceCodeEnd":555,"githubUrl":"https://github.com/openai/openai-python/blob/9917c6e28e66e90e1227b3d223c06a8c5441515a/src/openai/resources/realtime/realtime.py#L519-L555","documentation":"Raised by the async Realtime connection's dispatch_events when the server sends an `error` event and the application has registered no handler for that event type (neither a specific `@conn.on(\"error\")` handler nor a generic event handler). Rather than silently swallowing server errors, the SDK re-raises them as OpenAIError.","triggerScenarios":"Using `async for event in conn` or handler-based dispatch with no @on(\"error\") and no generic handler registered, while the server emits an error event (e.g. invalid session config, unknown function call id, rate limits).","commonSituations":"Prototyping realtime sessions without error handlers; malformed session.update payloads; sending events the model rejects.","solutions":["Register an explicit error handler: @conn.on(\"error\") async def on_error(event): ...","Or register a generic handler via @conn.on(\"event\") to receive all events including errors","Inspect event.error.code/message in the handler to fix the triggering client event","Validate session configuration before updating it"],"exampleFix":"# before\nasync with client.beta.realtime.connect(model=\"gpt-4o-realtime-preview\") as conn:\n    async for event in conn: ...\n# after\nasync with client.beta.realtime.connect(model=\"gpt-4o-realtime-preview\") as conn:\n    @conn.on(\"error\")\n    async def on_error(event):\n        logger.error(\"realtime error: %s\", event.error)\n    await conn.send(session_update)","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    async for event in conn:\n        handle(event)\nexcept OpenAIError as e:\n    if str(e).startswith(\"WebSocket error:\"):\n        logger.error(\"server error event: %s\", e)\n    else:\n        raise","preventionTips":["Always register @conn.on(\"error\") on realtime connections","Validate session.update payloads before sending","Handle unknown function-call ids correctly"],"tags":["realtime","websocket","async","server-error","event-handling"],"backgroundTag":"server-error-event-unhandled","analyzedSha":"9917c6e28e66e90e1227b3d223c06a8c5441515a","analyzedAt":"2026-08-28T11:46:34.183Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}