{"record":{"id":"510ac2060ac5d818","repo":"openai/openai-python","slug":"websocket-error-event","errorCode":null,"errorMessage":"WebSocket error: {event}","messagePattern":"WebSocket error: (.+?)","errorType":"exception","errorClass":"OpenAIError","httpStatus":null,"severity":"error","filePath":"src/openai/resources/beta/responses/responses.py","lineNumber":4373,"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, BetaResponseWsError):\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 AsyncResponsesConnectionManager:\n    \"\"\"\n    Context manager over a `AsyncResponsesConnection` that is returned by `beta.responses.connect()`\n\n    This context manager ensures that the connection will be closed when it exits.\n","sourceCodeStart":4355,"sourceCodeEnd":4391,"githubUrl":"https://github.com/openai/openai-python/blob/9917c6e28e66e90e1227b3d223c06a8c5441515a/src/openai/resources/beta/responses/responses.py#L4355-L4391","documentation":"The server sent an 'error' event over the WebSocket and the application registered no handler for 'error' (or a generic 'event' handler), so the SDK raises OpenAIError with the event payload to make the failure visible. If you register an 'error' handler, the exception is suppressed and the handler receives the event instead.","triggerScenarios":"Using the async BetaResponses WebSocket with event handlers (e.g. @conn.on(\"response.created\")) but no @conn.on(\"error\") or @conn.on(\"event\") handler, when the server pushes a BetaResponseWsError event (invalid request state, quota, protocol error).","commonSituations":"Realtime/voice-style flows where the server rejects malformed input audio, session updates, or the request hits rate limits/billing issues and the app never handled the error event type.","solutions":["Add an error handler: @conn.on(\"error\") to receive the event instead of an exception","Inspect the event payload in the handler to find the underlying server error code/message","Fix the client-side input that triggered the server error (invalid format, out-of-order events, auth)"],"exampleFix":"# before\n@conn.on(\"response.created\")\ndef on_created(ev): ...\n# after\n@conn.on(\"response.created\")\ndef on_created(ev): ...\n\n@conn.on(\"error\")\ndef on_error(ev):\n    print(\"server error:\", ev)","handlingStrategy":"fallback","validationCode":"conn.on(\"error\")(lambda ev: log_server_error(ev))  # register before consuming events","typeGuard":null,"tryCatchPattern":"try:\n    async for event in conn:\n        ...\nexcept OpenAIError as exc:\n    if \"WebSocket error\" in str(exc):\n        log_and_reconnect()","preventionTips":["Always register an @conn.on(\"error\") handler in realtime apps","Log the full error event payload to diagnose server-side causes"],"tags":["python","websocket","responses-api","event-handling","async"],"backgroundTag":"server-sent-error-event","analyzedSha":"9917c6e28e66e90e1227b3d223c06a8c5441515a","analyzedAt":"2026-08-28T11:46:34.183Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}