chore(api): document batch error responses

[markstuart-oai]

Summary

Documents Batch API error responses while preserving Java exception types and method signatures.

Changes

• Clarify invalid requests, missing batches, and cancellation conflicts.
• Describe applicable rate-limit and service-error responses.

[github-actions]

Castiron custom code

Mixed files: 89 → 92

3 newly customized · 0 customizations removed · 0 existing customizations changed · 3 generated baselines changed

Compared 59d019d42daf → ea4bf597a523. Generated baselines verified.

File	Result	Current custom patch
openai-java-core/src/main/kotlin/com/openai/models/audio/transcriptions/TranscriptionCreateParams.kt	Generated baseline changed	+2 / −3
openai-java-core/src/main/kotlin/com/openai/services/async/audio/TranscriptionServiceAsync.kt	Generated baseline changed	+4 / −6
openai-java-core/src/main/kotlin/com/openai/services/blocking/audio/TranscriptionService.kt	Generated baseline changed	+4 / −6

89 existing customizations unchanged

• openai-java-core/src/main/kotlin/com/openai/models/audio/AudioResponseFormat.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/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
• openai-java-core/src/main/kotlin/com/openai/services/blocking/BetaServiceImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/ResponseService.kt

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

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

git fetch --no-tags origin 59d019d42daf06d3369c76b7f98a00ee2c7c3d2f ea4bf597a523e9f76d280883357fba79f465fbfc
python3 scripts/castiron/custom_code_report.py report \
  --base 59d019d42daf06d3369c76b7f98a00ee2c7c3d2f \
  --head ea4bf597a523e9f76d280883357fba79f465fbfc --fetch --require-head-hash --public \
  --out /tmp/castiron-custom-code-ea4bf597a523
cat /tmp/castiron-custom-code-ea4bf597a523/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

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-25T07:03:11.004412Z	0a07bd7	Draft marked ready
🔒 Security Review	✅ Completed 2026-09-25T07:04:27.914104Z	0a07bd7	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[openai-sdks]

OkTest Summary

✅ 236/236 SDK tests passed in 11.546s for Java SDK PR #1082.

Test results — 42 files

Test	Result	Time
tests/chat-completions-complex-body.test.ts	✅ Passed	98ms
tests/chat-completions-create.test.ts	✅ Passed	283ms
tests/chat-completions-stream.test.ts	✅ Passed	279ms
tests/files-content-binary.test.ts	✅ Passed	156ms
tests/files-create-multipart.test.ts	✅ Passed	184ms
tests/files-list-pagination.test.ts	✅ Passed	168ms
tests/initialize-config.test.ts	✅ Passed	76ms
tests/instance-isolation.test.ts	✅ Passed	118ms
tests/models-list.test.ts	✅ Passed	145ms
tests/responses-background-lifecycle.test.ts	✅ Passed	156ms
tests/responses-body-method-errors.test.ts	✅ Passed	369ms
tests/responses-cancel-timeout.test.ts	✅ Passed	157ms
tests/responses-cancel.test.ts	✅ Passed	215ms
tests/responses-compact-retries.test.ts	✅ Passed	365ms
tests/responses-compact.test.ts	✅ Passed	166ms
tests/responses-create-advanced-stream.test.ts	✅ Passed	339ms
tests/responses-create-advanced.test.ts	✅ Passed	740ms
tests/responses-create-disconnect.test.ts	✅ Passed	1.071s
tests/responses-create-errors.test.ts	✅ Passed	244ms
tests/responses-create-malformed-api-responses.test.ts	✅ Passed	232ms
tests/responses-create-retries.test.ts	✅ Passed	203ms
tests/responses-create-stream-failures.test.ts	✅ Passed	145ms
tests/responses-create-stream-timeout.test.ts	✅ Passed	168ms
tests/responses-create-stream-wire.test.ts	✅ Passed	4.204s
tests/responses-create-stream.test.ts	✅ Passed	61ms
tests/responses-create-terminal-states.test.ts	✅ Passed	258ms
tests/responses-create-timeout.test.ts	✅ Passed	155ms
tests/responses-create.test.ts	✅ Passed	652ms
tests/responses-delete.test.ts	✅ Passed	169ms
tests/responses-input-items-errors.test.ts	✅ Passed	203ms
tests/responses-input-items-list.test.ts	✅ Passed	203ms
tests/responses-input-items-options.test.ts	✅ Passed	145ms
tests/responses-input-tokens-count-timeout.test.ts	✅ Passed	182ms
tests/responses-input-tokens-count.test.ts	✅ Passed	284ms
tests/responses-malformed-inputs.test.ts	✅ Passed	3.304s
tests/responses-not-found-errors.test.ts	✅ Passed	282ms
tests/responses-parse.test.ts	✅ Passed	403ms
tests/responses-retrieve-retries.test.ts	✅ Passed	290ms
tests/responses-retrieve.test.ts	✅ Passed	235ms
tests/responses-stored-method-errors.test.ts	✅ Passed	892ms
tests/retry-behavior.test.ts	✅ Passed	3.36s
tests/sdk-error-shape.test.ts	✅ Passed	368ms

View OkTest run #36168113806

_{SDK merge (daa93d0b9ac6) · head (ea4bf597a523) · base (59d019d42daf) · OkTest (bfef66d461d0)}

[markstuart-oai]

Resolved the merge conflicts at ea4bf597a523e9f76d280883357fba79f465fbfc, based on current main 59d019d42daf06d3369c76b7f98a00ee2c7c3d2f.

The final diff changes only the API reference and generation metadata. All Java/Kotlin client code, public APIs, exception handling, dependencies, tests, and workflows remain byte-for-byte identical to that baseline, including the newly merged audio changes. The reference comparison confirms only the intended Batch error-response additions; the exact-head local merge check is clean.

Independent review and formatting passed. All 14 reported checks/statuses on this head are terminal: 13 successful and one intentionally skipped. Fresh CI includes API/Jackson compatibility, Java 8/25 runtime checks, and tests; both custom-code checks pass. The updated head also has human approval. The downstream compatibility suite also passed all 236 tests for this updated head.