Repository navigation
Realtime API Pydantic Models incomplete for RealtimeResponseStatus type #2502
Description
Confirm this is an issue with the Python library and not an underlying OpenAI API
- This is an issue with the Python library --> It is both and I have informed the issue via https://help.openai.com/en
Describe the bug
And I have got errors like this when using latest Azure deployments of OpenAI Realtime model
{
"type": "response.done",
"event_id": "event_BvlnvdNtqw7LLGP7xDfyA",
"response": {
"object": "realtime.response",
"id": "resp_BvlnvRcuxxRLrr5FBygyo",
"status": "failed",
"status_details": {
"type": "failed",
"error": {
"type": "invalid_request_error",
"code": "inference_rate_limit_exceeded",
"message": "We're currently processing too many requests — please try again later."
}
},
"output": [],
"conversation_id": "conv_Bvlm1z1fjvrisuRsPx8hC",
"modalities": ["text", "audio"],
"voice": "sage",
"output_audio_format": "pcm16",
"temperature": 0.6,
"max_output_tokens": "inf",
"usage": {
"total_tokens": 0,
"input_tokens": 0,
"output_tokens": 0,
"input_token_details": {
"text_tokens": 0,
"audio_tokens": 0,
"cached_tokens": 0,
"cached_tokens_details": {
"text_tokens": 0,
"audio_tokens": 0
}
},
"output_token_details": {
"text_tokens": 0,
"audio_tokens": 0
}
},
"metadata": {
"client_event_id": "response_create_6448171658c7"
}
}
}I have seen online others report errors like this: https://community.openai.com/t/realtime-api-errors-in-both-playground-and-api-calls/1007933 or here pipecat-ai/pipecat#2106 (comment) etc.
The problem is that the pydantic model for Error is wrong - it does not include the message field (e.g. "We're currently processing too many requests — please try again later." in the above example). This seems to be the case in the API reference itself too https://platform.openai.com/docs/api-reference/realtime-server-events/response/done
A side effect of this is that pydantic validated code sometimes will omit the message which is quite helpeful for debugging.
To Reproduce
Create a response that fails to complete, e.g. due to exceeding the rate limit of your server
The issue is present even in latest code base of openai repo:
Code snippets
OS
Linux
Python version
3.13
Library version
1.84.0
Activity
bml1g12 commentedon Jul 30, 2025
hmm maybe I should make this issue in a more general place as it affects the general API too - will close it
bml1g12 commentedon Jul 30, 2025
I contacted OpenAI via the bot on https://help.openai.com/en to report this documentation/type mismatch issue but it said it was unable to provide me updates on the progress of the bug fix, so I will keep this issue open until it is addressed. If there is a better way to track open bugs for the OpenAI API reference itself, please keep me informed and I will close this
Specifically the bot said to me
fix: Add missing statuses to RealtimeResponseStatus model (openai#2502)
bml1g12 commentedon Jul 31, 2025
Thanks I have replied on the PR LuminaX-alt@4aa669c#commitcomment-163212994
bml1g12 commentedon Aug 7, 2025
@RobertCraigie thanks for helping get the visibility on this one, I see @LuminaX-alt has made a PR labelled as addressing this but I wanted to clarify that it is not currently fixing the issue raised for the reason explained here - are you able to make sure that gets visiblity too?
thanks !
fscfede-beep commentedon Sep 8, 2026
Audited against current main:
src/openai/types/beta/realtime/realtime_response_status.pystill definesErrorwith onlycodeandtype; there is no open PR currently attached to #2502. The reported wire payload contains a human-readablemessage, so Pydantic drops information that users need for diagnosis.Proposed minimal fix (generated-model compatible): add
message: Optional[str] = Nonewith the same generated-field style, then add a focused model regression that validates a failedRealtimeResponseStatuspayload containingerror.messageand asserts the value is preserved. Also assert omission remains valid (Error(code=...)=>message is None).Correct invariant:
wire.error.message -> Error.message -> consumerwith no behavioral change when the field is absent.
I would keep this limited to the schema/model layer; no runtime exception handling or transport changes are needed. Because this file is generated, the durable fix should also update the generator/OpenAPI source (or whatever generated-source contract produces this model) rather than relying on a handwritten edit that could be overwritten.
This is intentionally a two-line semantic correction plus a regression test: low regression surface, directly tied to the public Realtime payload contract, and easy to review.
fscfede-beep commentedon Sep 8, 2026
Implementation-ready patch prepared against current main: add
message: Optional[str] = NonetoRealtimeResponseStatus.Error, preserving the wire-level human-readable error, plus regression tests for present and omitted message.The invariant is
wire.error.message -> Error.message -> consumer; absent message remainsNone. This is intentionally limited to schema preservation. Because the model file is generated, the durable upstream source should be updated at the generator/OpenAPI contract so regeneration reproduces the field. I did not modify the upstream repository because the integration has no write permission there.fix(api): declare Realtime response error messages (openai#4083)