{"record":{"id":"82f7bfc4c7f9b30c","repo":"openai/openai-python","slug":"websocket-error-event-82f7bf","errorCode":null,"errorMessage":"WebSocket error: {event}","messagePattern":"WebSocket error: (.+?)","errorType":"exception","errorClass":"OpenAIError","httpStatus":null,"severity":"error","filePath":"src/openai/resources/responses/responses.py","lineNumber":4268,"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, ResponseWsError):\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 `responses.connect()`\n\n    This context manager ensures that the connection will be closed when it exits.\n","sourceCodeStart":4250,"sourceCodeEnd":4286,"githubUrl":"https://github.com/openai/openai-python/blob/9917c6e28e66e90e1227b3d223c06a8c5441515a/src/openai/resources/responses/responses.py#L4250-L4286","documentation":"Raised by dispatch_events() on a Responses WebSocket when the server sends an 'error' event and no handler (neither the specific 'error' handler nor a generic 'event' handler) is registered to consume it. Unhandled WebSocket-level errors are promoted to an OpenAIError so they are not silently swallowed.","triggerScenarios":"Registering event handlers for e.g. 'response.output_text.delta' but not for 'error' (nor a catch-all 'event' handler); the server then emits ResponseWsError (e.g. invalid session update, auth problem) and no one is listening.","commonSituations":"Selective handler registration that ignores error events; porting webhook/sse handler code that assumed errors always raise; server-side rate limits or malformed requests surfacing as ws error events.","solutions":["Register an 'error' handler: @conn.on('error') async def on_error(e): ...","Or register a generic 'event' handler to observe every server event including errors","Log the error payload to identify the server-side cause (e.g. session config rejected)"],"exampleFix":"// before\n@conn.on(\"response.output_text.delta\")\nasync def on_delta(e): ...\n// after\n@conn.on(\"response.output_text.delta\")\nasync def on_delta(e): ...\n\n@conn.on(\"error\")\nasync def on_error(e):\n    logger.error(\"ws error: %s\", e)","handlingStrategy":"try-catch","validationCode":"handlers = conn._event_handler_registry.get_handlers('error')\nif not handlers and not conn._event_handler_registry.get_handlers('event'):\n    raise RuntimeError('register an error handler before dispatching')","typeGuard":"def has_error_handler(conn) -> bool:\n    reg = conn._event_handler_registry\n    return bool(reg.get_handlers('error') or reg.get_handlers('event'))","tryCatchPattern":"from openai import OpenAIError\ntry:\n    await conn.dispatch_events()\nexcept OpenAIError as e:\n    if str(e).startswith('WebSocket error:'):\n        logger.error('server-side ws error: %s', e)\n        await recover()\n    else:\n        raise","preventionTips":["Always register an 'error' handler on WebSocket connections","Or add a generic 'event' handler to observe server error events","Log error payloads to diagnose session/config problems early"],"tags":["websocket","responses","error-event","event-handlers","python"],"backgroundTag":"unhandled-server-error-event","analyzedSha":"9917c6e28e66e90e1227b3d223c06a8c5441515a","analyzedAt":"2026-08-28T11:46:34.183Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}