openai/openai-python · error · OpenAIError

WebSocket error: {event}

Error message

WebSocket error: {event}

What it means

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.

Source

Thrown at src/openai/resources/beta/responses/responses.py:4373

    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, BetaResponseWsError):
                    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 AsyncResponsesConnectionManager:
    """
    Context manager over a `AsyncResponsesConnection` that is returned by `beta.responses.connect()`

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

View on GitHub (pinned to 9917c6e28e)

Solutions

1. Add an error handler: @conn.on("error") to receive the event instead of an exception
2. Inspect the event payload in the handler to find the underlying server error code/message
3. Fix the client-side input that triggered the server error (invalid format, out-of-order events, auth)

Example fix

# before
@conn.on("response.created")
def on_created(ev): ...
# after
@conn.on("response.created")
def on_created(ev): ...

@conn.on("error")
def on_error(ev):
    print("server error:", ev)

conn.on("error")(lambda ev: log_server_error(ev))  # register before consuming events

try:
    async for event in conn:
        ...
except OpenAIError as exc:
    if "WebSocket error" in str(exc):
        log_and_reconnect()

When it happens

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

Common situations: 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.

Related errors

• WebSocket connection closed with unsent messages
• WebSocket error: {event}
• max_retries cannot be None. If you want to disable retries,
• Unexpected JSON data type, {type(json_data)}, cannot merge w
• Expected query input to be a dictionary for multipart reques

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