chore(api): document stored chat completion errors

[markstuart-oai]

Summary

Documents errors for stored chat completions while preserving Java method signatures and exception types.

Changes

• Describe applicable errors for stored completion operations and message listing.
• Leave existing client behavior and chat completion creation unchanged.

[github-actions]

Castiron custom code

✅ No new custom-code files detected.

92 mixed files remain; 0 existing customizations changed.

Compared 840bb120c0d3 → 83f83bbd05a9. Generated baselines verified.

92 existing customizations unchanged

• openai-java-core/src/main/kotlin/com/openai/models/audio/AudioResponseFormat.kt
• openai-java-core/src/main/kotlin/com/openai/models/audio/transcriptions/TranscriptionCreateParams.kt
• openai-java-core/src/main/kotlin/com/openai/models/beta/agents/vaults/credentials/CredentialAuth.kt
• openai-java-core/src/main/kotlin/com/openai/models/beta/agents/vaults/credentials/CredentialAuthCreateParam.kt
• openai-java-core/src/main/kotlin/com/openai/models/beta/agents/vaults/credentials/CredentialAuthRotateParam.kt
• openai-java-core/src/main/kotlin/com/openai/models/beta/responses/BetaResponseStreamEvent.kt
• openai-java-core/src/main/kotlin/com/openai/models/beta/responses/BetaResponsesServerEvent.kt
• openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionCreateParams.kt
• openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionMessageFunctionToolCall.kt
• openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionToolMessageParam.kt
• openai-java-core/src/main/kotlin/com/openai/models/embeddings/Embedding.kt
• openai-java-core/src/main/kotlin/com/openai/models/embeddings/EmbeddingCreateParams.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseCreateParams.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseFunctionToolCall.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseFunctionWebSearch.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseInputItem.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseStreamEvent.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseTextConfig.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponsesServerEvent.kt
• openai-java-core/src/main/kotlin/com/openai/models/videos/Video.kt
• openai-java-core/src/main/kotlin/com/openai/models/webhooks/UnwrapWebhookEvent.kt
• openai-java-core/src/main/kotlin/com/openai/models/webhooks/WebhookEndpointWithSecret.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/BetaServiceAsync.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/BetaServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/ImageServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/ResponseServiceAsync.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/ResponseServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/SkillServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/VideoServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/WebhookServiceAsync.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/WebhookServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/audio/TranscriptionServiceAsync.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/audio/TranscriptionServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/audio/TranslationServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/beta/agents/SessionServiceAsync.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/beta/agents/SessionServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/chat/ChatCompletionServiceAsync.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/finetuning/checkpoints/PermissionServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/skills/VersionServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/BetaService.kt

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

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

git fetch --no-tags origin 840bb120c0d37313aa494ef2bd3a6981a2089341 83f83bbd05a9cb3a1a2dac1868149012822793a3
python3 scripts/castiron/custom_code_report.py report \
  --base 840bb120c0d37313aa494ef2bd3a6981a2089341 \
  --head 83f83bbd05a9cb3a1a2dac1868149012822793a3 --fetch --require-head-hash --public \
  --out /tmp/castiron-custom-code-83f83bbd05a9
cat /tmp/castiron-custom-code-83f83bbd05a9/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 18.251s for Java SDK PR #1086.

Test results — 42 files

Test	Result	Time
tests/chat-completions-complex-body.test.ts	✅ Passed	800ms
tests/chat-completions-create.test.ts	✅ Passed	531ms
tests/chat-completions-stream.test.ts	✅ Passed	775ms
tests/files-content-binary.test.ts	✅ Passed	280ms
tests/files-create-multipart.test.ts	✅ Passed	398ms
tests/files-list-pagination.test.ts	✅ Passed	243ms
tests/initialize-config.test.ts	✅ Passed	127ms
tests/instance-isolation.test.ts	✅ Passed	116ms
tests/models-list.test.ts	✅ Passed	315ms
tests/responses-background-lifecycle.test.ts	✅ Passed	219ms
tests/responses-body-method-errors.test.ts	✅ Passed	550ms
tests/responses-cancel-timeout.test.ts	✅ Passed	223ms
tests/responses-cancel.test.ts	✅ Passed	319ms
tests/responses-compact-retries.test.ts	✅ Passed	329ms
tests/responses-compact.test.ts	✅ Passed	223ms
tests/responses-create-advanced-stream.test.ts	✅ Passed	389ms
tests/responses-create-advanced.test.ts	✅ Passed	1.479s
tests/responses-create-disconnect.test.ts	✅ Passed	1.109s
tests/responses-create-errors.test.ts	✅ Passed	501ms
tests/responses-create-malformed-api-responses.test.ts	✅ Passed	224ms
tests/responses-create-retries.test.ts	✅ Passed	274ms
tests/responses-create-stream-failures.test.ts	✅ Passed	264ms
tests/responses-create-stream-timeout.test.ts	✅ Passed	377ms
tests/responses-create-stream-wire.test.ts	✅ Passed	7.86s
tests/responses-create-stream.test.ts	✅ Passed	402ms
tests/responses-create-terminal-states.test.ts	✅ Passed	347ms
tests/responses-create-timeout.test.ts	✅ Passed	288ms
tests/responses-create.test.ts	✅ Passed	708ms
tests/responses-delete.test.ts	✅ Passed	284ms
tests/responses-input-items-errors.test.ts	✅ Passed	258ms
tests/responses-input-items-list.test.ts	✅ Passed	395ms
tests/responses-input-items-options.test.ts	✅ Passed	173ms
tests/responses-input-tokens-count-timeout.test.ts	✅ Passed	198ms
tests/responses-input-tokens-count.test.ts	✅ Passed	198ms
tests/responses-malformed-inputs.test.ts	✅ Passed	6.676s
tests/responses-not-found-errors.test.ts	✅ Passed	520ms
tests/responses-parse.test.ts	✅ Passed	435ms
tests/responses-retrieve-retries.test.ts	✅ Passed	243ms
tests/responses-retrieve.test.ts	✅ Passed	297ms
tests/responses-stored-method-errors.test.ts	✅ Passed	939ms
tests/retry-behavior.test.ts	✅ Passed	3.576s
tests/sdk-error-shape.test.ts	✅ Passed	482ms

View OkTest run #36173583296

_{SDK merge (06e1a679ebb0) · head (83f83bbd05a9) · base (840bb120c0d3) · OkTest (f9111d4e2fcd)}

[jbeckwith-oai]

Reviewed 83f83bbd05a9cb3a1a2dac1868149012822793a3 — no actionable findings.

Independently parsed and compared the complete base/head OpenAPI artifacts: exactly 17 documented error responses are added across the five stored Chat Completion operations; all other semantic content is unchanged. Every new schema/response reference resolves, and the transformed-spec checksum matches .castiron.stats.yml. The full two-file diff leaves Java/Kotlin APIs, exception types, runtime code, dependencies, and workflows unchanged.

All reported exact-head repository CI checks are green, including API/Jackson compatibility and Java 8/25 runtime tests. The separately reported downstream compatibility run is not included in that statement and remains to be verified. I did not rerun Gradle or make live API calls locally for this documentation-only change.

[markstuart-oai]

Thanks for the independent review. The approved head is unchanged: only the API reference and generation metadata differ from main, with all Java/Kotlin APIs, exception handling and runtime code preserved. PR checks pass. The separate downstream compatibility run has now also passed all 236 cases.