chore(api): document stored chat completion errors

[markstuart-oai]

Summary

Clarifies error responses for stored chat completions without changing Python exception handling.

Changes

• Document applicable lookup, validation, rate-limit and service errors.
• Preserve existing methods, return types and exception behavior.

[github-actions]

Castiron custom code

✅ No new custom-code files detected.

47 mixed files remain; 0 existing customizations changed.

Compared 6e4a79cc8c7e → 8f80409efdcc. Generated baselines verified.

47 existing customizations unchanged

• api.md
• scripts/castiron/README.md
• scripts/castiron/custom_code_report.py
• scripts/castiron/test_custom_code_report.py
• src/openai/init.py
• src/openai/_client.py
• src/openai/resources/audio/transcriptions.py
• src/openai/resources/audio/translations.py
• src/openai/resources/beta/agents/sessions/sessions.py
• src/openai/resources/beta/beta.py
• src/openai/resources/beta/responses/responses.py
• src/openai/resources/beta/threads/runs/runs.py
• src/openai/resources/beta/threads/threads.py
• src/openai/resources/chat/completions/completions.py
• src/openai/resources/embeddings.py
• src/openai/resources/files.py
• src/openai/resources/live/forks.py
• src/openai/resources/live/live.py
• src/openai/resources/live/sideband.py
• src/openai/resources/realtime/api.md
• src/openai/resources/realtime/realtime.py
• src/openai/resources/responses/responses.py
• src/openai/resources/uploads/uploads.py
• src/openai/resources/vector_stores/file_batches.py
• src/openai/resources/vector_stores/files.py
• src/openai/resources/videos.py
• src/openai/resources/webhooks/init.py
• src/openai/resources/webhooks/webhooks.py
• src/openai/types/beta/agent_session_message.py
• src/openai/types/chat/init.py
• src/openai/types/chat/chat_completion_message_tool_call.py
• src/openai/types/fine_tuning/fine_tuning_job_integration.py
• src/openai/types/realtime/conversation_item_input_audio_transcription_delta_event.py
• src/openai/types/realtime/realtime_error_event.py
• src/openai/types/responses/init.py
• src/openai/types/responses/response.py
• src/openai/types/responses/response_function_web_search.py
• src/openai/types/responses/response_function_web_search_param.py
• src/openai/types/responses/responses_client_event.py
• src/openai/types/responses/responses_client_event_param.py

7 more in the full report.

A changed generated baseline means this report cannot reliably identify which handwritten lines changed.

Inspect the custom-code diff

Download the exact patch produced by this run (requires repository access):

gh run download 36170591942 --repo openai/openai-python \
  --name castiron-custom-code-36170591942-1 --dir /tmp/castiron-custom-code-36170591942-1
git apply --stat /tmp/castiron-custom-code-36170591942-1/custom-code.patch
cat /tmp/castiron-custom-code-36170591942-1/custom-code.patch

Or reproduce it from an SDK checkout containing the vendored reporter:

git fetch --no-tags origin 6e4a79cc8c7e640e7ac4be710db32fe20b1020f2 8f80409efdccf04bc238530bc6a4442aa9128cec
python3 scripts/castiron/custom_code_report.py report \
  --base 6e4a79cc8c7e640e7ac4be710db32fe20b1020f2 \
  --head 8f80409efdccf04bc238530bc6a4442aa9128cec --fetch --require-head-hash --public \
  --out /tmp/castiron-custom-code-8f80409efdcc
cat /tmp/castiron-custom-code-8f80409efdcc/custom-code.patch

This is the current full custom patch for mixed files, not an attribution of only the handwritten lines changed by this PR.

Full report and patch

[openai-sdks]

OkTest Summary

✅ 236/236 SDK tests passed in 10.247s for Python SDK PR #3963.

Test results — 42 files

Test	Result	Time
tests/chat-completions-complex-body.test.ts	✅ Passed	295ms
tests/chat-completions-create.test.ts	✅ Passed	197ms
tests/chat-completions-stream.test.ts	✅ Passed	267ms
tests/files-content-binary.test.ts	✅ Passed	179ms
tests/files-create-multipart.test.ts	✅ Passed	174ms
tests/files-list-pagination.test.ts	✅ Passed	122ms
tests/initialize-config.test.ts	✅ Passed	131ms
tests/instance-isolation.test.ts	✅ Passed	158ms
tests/models-list.test.ts	✅ Passed	166ms
tests/responses-background-lifecycle.test.ts	✅ Passed	156ms
tests/responses-body-method-errors.test.ts	✅ Passed	317ms
tests/responses-cancel-timeout.test.ts	✅ Passed	208ms
tests/responses-cancel.test.ts	✅ Passed	179ms
tests/responses-compact-retries.test.ts	✅ Passed	318ms
tests/responses-compact.test.ts	✅ Passed	284ms
tests/responses-create-advanced-stream.test.ts	✅ Passed	383ms
tests/responses-create-advanced.test.ts	✅ Passed	196ms
tests/responses-create-disconnect.test.ts	✅ Passed	1.21s
tests/responses-create-errors.test.ts	✅ Passed	157ms
tests/responses-create-malformed-api-responses.test.ts	✅ Passed	170ms
tests/responses-create-retries.test.ts	✅ Passed	193ms
tests/responses-create-stream-failures.test.ts	✅ Passed	167ms
tests/responses-create-stream-timeout.test.ts	✅ Passed	236ms
tests/responses-create-stream-wire.test.ts	✅ Passed	3.053s
tests/responses-create-stream.test.ts	✅ Passed	126ms
tests/responses-create-terminal-states.test.ts	✅ Passed	217ms
tests/responses-create-timeout.test.ts	✅ Passed	199ms
tests/responses-create.test.ts	✅ Passed	486ms
tests/responses-delete.test.ts	✅ Passed	160ms
tests/responses-input-items-errors.test.ts	✅ Passed	463ms
tests/responses-input-items-list.test.ts	✅ Passed	304ms
tests/responses-input-items-options.test.ts	✅ Passed	249ms
tests/responses-input-tokens-count-timeout.test.ts	✅ Passed	248ms
tests/responses-input-tokens-count.test.ts	✅ Passed	159ms
tests/responses-malformed-inputs.test.ts	✅ Passed	2.146s
tests/responses-not-found-errors.test.ts	✅ Passed	242ms
tests/responses-parse.test.ts	✅ Passed	218ms
tests/responses-retrieve-retries.test.ts	✅ Passed	181ms
tests/responses-retrieve.test.ts	✅ Passed	174ms
tests/responses-stored-method-errors.test.ts	✅ Passed	581ms
tests/retry-behavior.test.ts	✅ Passed	3.093s
tests/sdk-error-shape.test.ts	✅ Passed	408ms

View OkTest run #36170553722

_{SDK merge (13b8f52aefce) · head (8f80409efdcc) · base (6e4a79cc8c7e) · OkTest (bfef66d461d0)}

[jbeckwith-oai]

Reviewed 8f80409 against 6e4a79c. No actionable findings.

Independently parsed the complete base/head OpenAPI documents and verified that the entire semantic difference is exactly 17 added error-response entries across the five stored-chat operations (list, retrieve, update, delete, and list messages). Removing those entries makes the full documents equal. The ErrorResponse and TooManyRequests references resolve to unchanged existing components, and chat-completion creation/streaming definitions are unchanged.

Verified the transformed-document MD5 matches generation metadata (6e1ff6e06165d5b2e49cbfd336f00c20); only the expected five generation metadata fields changed. Both changed files were reviewed; no SDK implementation, public signatures, exception classes, or dependency files changed.

Validation was artifact-focused for this documentation-only change. I did not rerun the full SDK test suite or make live API calls.

[markstuart-oai]

Thanks for the independent review. Confirmed the reviewed head is unchanged: only the API reference and generation metadata differ from main. Python client code and exception handling remain byte-identical; the current CI and 236-case downstream compatibility run both pass.