chore(api): clarify documented API error responses

[markstuart-oai]

Summary

Clarifies documented error responses for Ruby users without changing existing client behavior.

Changes

• Document applicable errors across organization, inference, media and resource APIs.
• Preserve existing public methods, exception types and runtime behavior.

[github-actions]

Castiron custom code

✅ No new custom-code files detected.

70 mixed files remain; 0 existing customizations changed.

Compared 4b3b04317641 → 9ddd667af9ff. Generated baselines verified.

70 existing customizations unchanged

• lib/openai.rb
• lib/openai/client.rb
• lib/openai/models/audio/transcription_create_response.rb
• lib/openai/models/beta/agents/vault_status_filter.rb
• lib/openai/models/chat/chat_completion_message.rb
• lib/openai/models/chat/chat_completion_message_function_tool_call.rb
• lib/openai/models/chat/completion_create_params.rb
• lib/openai/models/image_edit_completed_event.rb
• lib/openai/models/image_edit_partial_image_event.rb
• lib/openai/models/image_gen_completed_event.rb
• lib/openai/models/image_gen_partial_image_event.rb
• lib/openai/models/images_response.rb
• lib/openai/models/response_format_json_schema.rb
• lib/openai/models/responses/function_tool.rb
• lib/openai/models/responses/response.rb
• lib/openai/models/responses/response_create_params.rb
• lib/openai/models/responses/response_format_text_config.rb
• lib/openai/models/responses/response_format_text_json_schema_config.rb
• lib/openai/models/responses/response_function_tool_call.rb
• lib/openai/models/responses/response_function_web_search.rb
• lib/openai/models/responses/response_output_text.rb
• lib/openai/models/responses/tool.rb
• lib/openai/models/webhooks/webhook_endpoint_with_secret.rb
• lib/openai/resources/beta/agents/sessions.rb
• lib/openai/resources/beta/threads.rb
• lib/openai/resources/chat/completions.rb
• lib/openai/resources/containers/files.rb
• lib/openai/resources/files.rb
• lib/openai/resources/responses.rb
• lib/openai/resources/vector_stores/file_batches.rb
• lib/openai/resources/vector_stores/files.rb
• lib/openai/resources/webhooks.rb
• rbi/openai/client.rbi
• rbi/openai/models/beta/agents/vault_status_filter.rbi
• rbi/openai/models/chat/chat_completion_message.rbi
• rbi/openai/models/chat/chat_completion_message_function_tool_call.rbi
• rbi/openai/models/chat/completion_create_params.rbi
• rbi/openai/models/image_edit_completed_event.rbi
• rbi/openai/models/image_edit_partial_image_event.rbi
• rbi/openai/models/image_gen_completed_event.rbi

30 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 36188994318 --repo openai/openai-ruby \
  --name castiron-custom-code-36188994318-1 --dir /tmp/castiron-custom-code-36188994318-1
git apply --stat /tmp/castiron-custom-code-36188994318-1/custom-code.patch
cat /tmp/castiron-custom-code-36188994318-1/custom-code.patch

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

git fetch --no-tags origin 4b3b043176413f6c70309290bf8f4129a8961c16 9ddd667af9ff60406de076e5da4b07105ad0aacc
python3 scripts/castiron/custom_code_report.py report \
  --base 4b3b043176413f6c70309290bf8f4129a8961c16 \
  --head 9ddd667af9ff60406de076e5da4b07105ad0aacc --fetch --require-head-hash --public \
  --out /tmp/castiron-custom-code-9ddd667af9ff
cat /tmp/castiron-custom-code-9ddd667af9ff/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 8.24s for Ruby SDK PR #765.

Test results — 42 files

Test	Result	Time
tests/chat-completions-complex-body.test.ts	✅ Passed	125ms
tests/chat-completions-create.test.ts	✅ Passed	186ms
tests/chat-completions-stream.test.ts	✅ Passed	110ms
tests/files-content-binary.test.ts	✅ Passed	133ms
tests/files-create-multipart.test.ts	✅ Passed	116ms
tests/files-list-pagination.test.ts	✅ Passed	143ms
tests/initialize-config.test.ts	✅ Passed	125ms
tests/instance-isolation.test.ts	✅ Passed	106ms
tests/models-list.test.ts	✅ Passed	141ms
tests/responses-background-lifecycle.test.ts	✅ Passed	131ms
tests/responses-body-method-errors.test.ts	✅ Passed	307ms
tests/responses-cancel-timeout.test.ts	✅ Passed	237ms
tests/responses-cancel.test.ts	✅ Passed	220ms
tests/responses-compact-retries.test.ts	✅ Passed	145ms
tests/responses-compact.test.ts	✅ Passed	196ms
tests/responses-create-advanced-stream.test.ts	✅ Passed	213ms
tests/responses-create-advanced.test.ts	✅ Passed	150ms
tests/responses-create-disconnect.test.ts	✅ Passed	126ms
tests/responses-create-errors.test.ts	✅ Passed	278ms
tests/responses-create-malformed-api-responses.test.ts	✅ Passed	114ms
tests/responses-create-retries.test.ts	✅ Passed	209ms
tests/responses-create-stream-failures.test.ts	✅ Passed	138ms
tests/responses-create-stream-timeout.test.ts	✅ Passed	200ms
tests/responses-create-stream-wire.test.ts	✅ Passed	1.868s
tests/responses-create-stream.test.ts	✅ Passed	169ms
tests/responses-create-terminal-states.test.ts	✅ Passed	232ms
tests/responses-create-timeout.test.ts	✅ Passed	229ms
tests/responses-create.test.ts	✅ Passed	141ms
tests/responses-delete.test.ts	✅ Passed	110ms
tests/responses-input-items-errors.test.ts	✅ Passed	153ms
tests/responses-input-items-list.test.ts	✅ Passed	166ms
tests/responses-input-items-options.test.ts	✅ Passed	98ms
tests/responses-input-tokens-count-timeout.test.ts	✅ Passed	231ms
tests/responses-input-tokens-count.test.ts	✅ Passed	125ms
tests/responses-malformed-inputs.test.ts	✅ Passed	2.121s
tests/responses-not-found-errors.test.ts	✅ Passed	280ms
tests/responses-parse.test.ts	✅ Passed	140ms
tests/responses-retrieve-retries.test.ts	✅ Passed	129ms
tests/responses-retrieve.test.ts	✅ Passed	194ms
tests/responses-stored-method-errors.test.ts	✅ Passed	617ms
tests/retry-behavior.test.ts	✅ Passed	3.196s
tests/sdk-error-shape.test.ts	✅ Passed	518ms

View OkTest run #36188960100

_{SDK merge (e76708bd01fe) · head (9ddd667af9ff) · base (4b3b04317641) · OkTest (f9111d4e2fcd)}

[markstuart-oai]

Thanks for reviewing. The approved head is unchanged and still contains only the error-reference update and generation metadata; existing client APIs, exception types and runtime behavior are preserved.