openai/openai-python · error · OpenAIError

WebSocket error: {event}

Error message

WebSocket error: {event}

What it means

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.

Source

Thrown at src/openai/resources/realtime/realtime.py:537

    async def dispatch_events(self) -> None:
        """Run the event loop, dispatching received events to registered handlers.

        Blocks until the connection is closed. This is the push-based
        alternative to iterating with ``async for event in connection``.

        If an ``"error"`` event arrives and no handler is registered for
        ``"error"`` or ``"event"``, an ``OpenAIError`` is raised.
        """
        import asyncio

        async for event in self:
            event_type = event.type
            specific = self._event_handler_registry.get_handlers(event_type)
            generic = self._event_handler_registry.get_handlers("event")

            if event_type == "error" and not specific and not generic:
                if isinstance(event, RealtimeErrorEvent):
                    raise OpenAIError(f"WebSocket error: {event}")

            for handler in specific:
                result = handler(event)
                if asyncio.iscoroutine(result):
                    await result

            for handler in generic:
                result = handler(event)
                if asyncio.iscoroutine(result):
                    await result


class AsyncRealtimeConnectionManager:
    """
    Context manager over a `AsyncRealtimeConnection` that is returned by `realtime.connect()`

    This context manager ensures that the connection will be closed when it exits.

View on GitHub (pinned to 9917c6e28e)

Solutions

1. Register an explicit error handler: @conn.on("error") async def on_error(event): ...
2. Or register a generic handler via @conn.on("event") to receive all events including errors
3. Inspect event.error.code/message in the handler to fix the triggering client event
4. Validate session configuration before updating it

Example fix

# before
async with client.beta.realtime.connect(model="gpt-4o-realtime-preview") as conn:
    async for event in conn: ...
# after
async with client.beta.realtime.connect(model="gpt-4o-realtime-preview") as conn:
    @conn.on("error")
    async def on_error(event):
        logger.error("realtime error: %s", event.error)
    await conn.send(session_update)

try:
    async for event in conn:
        handle(event)
except OpenAIError as e:
    if str(e).startswith("WebSocket error:"):
        logger.error("server error event: %s", e)
    else:
        raise

When it happens

Trigger: 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).

Common situations: Prototyping realtime sessions without error handlers; malformed session.update payloads; sending events the model rejects.

Related errors

• WebSocket error: {event}
• WebSocket connection closed with unsent messages
• You need to install `openai[realtime]` to use this method
• WebSocket connection closed with unsent messages
• You need to install `openai[realtime]` to use this method

AI-assisted analysis of openai/openai-python@9917c6e28e (2026-08-28). Data as JSON: /api/errors/f60f0b3b66d50f3c. Report an issue: GitHub.