Skip to content

chore(api): document API error response contracts - #1039

Open
markstuart-oai wants to merge 1 commit into
mainfrom
castiron/promotions/pr-126
Open

markstuart-oai wants to merge 1 commit into
mainfrom
castiron/promotions/pr-126

Conversation

@markstuart-oai

Copy link
Copy Markdown
Contributor

Summary

Clarifies documented HTTP errors while preserving Java client behavior.

Changes

  • Describe verified failure statuses, error envelopes and applicable retry headers.
  • Preserve existing Java client types and methods.

@github-actions

github-actions Bot commented Sep 20, 2026

Copy link
Copy Markdown
Contributor

Castiron custom code

✅ No new custom-code files detected.

83 mixed files remain; 0 existing customizations changed.

Compared d2969f8efd585ec062e0604a. Generated baselines verified.

83 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/ResponseServiceAsync.kt
  • openai-java-core/src/main/kotlin/com/openai/services/async/ResponseServiceAsyncImpl.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/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/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
  • openai-java-core/src/main/kotlin/com/openai/services/blocking/ResponseServiceImpl.kt
  • openai-java-core/src/main/kotlin/com/openai/services/blocking/WebhookService.kt
  • openai-java-core/src/main/kotlin/com/openai/services/blocking/WebhookServiceImpl.kt
  • openai-java-core/src/main/kotlin/com/openai/services/blocking/audio/TranscriptionServiceImpl.kt
  • openai-java-core/src/main/kotlin/com/openai/services/blocking/beta/agents/SessionService.kt

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

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

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

@markstuart-oai
markstuart-oai marked this pull request as ready for review September 20, 2026 17:41
@markstuart-oai
markstuart-oai requested a review from a team as a code owner September 20, 2026 17:41
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 20, 2026

Copy link
Copy Markdown

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-20T18:55:37.165005Z 5ec062e New commits
🔒 Security Review Completed 2026-09-20T18:56:02.249729Z 5ec062e New commits
ℹ️ 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

openai-sdks Bot commented Sep 20, 2026

Copy link
Copy Markdown
Contributor

OkTest Summary

236/236 SDK tests passed in 15.024s for Java SDK PR #1039.

Test results — 42 files
Test Result Time
tests/chat-completions-complex-body.test.ts ✅ Passed 152ms
tests/chat-completions-create.test.ts ✅ Passed 719ms
tests/chat-completions-stream.test.ts ✅ Passed 489ms
tests/files-content-binary.test.ts ✅ Passed 205ms
tests/files-create-multipart.test.ts ✅ Passed 446ms
tests/files-list-pagination.test.ts ✅ Passed 230ms
tests/initialize-config.test.ts ✅ Passed 123ms
tests/instance-isolation.test.ts ✅ Passed 251ms
tests/models-list.test.ts ✅ Passed 361ms
tests/responses-background-lifecycle.test.ts ✅ Passed 203ms
tests/responses-body-method-errors.test.ts ✅ Passed 388ms
tests/responses-cancel-timeout.test.ts ✅ Passed 225ms
tests/responses-cancel.test.ts ✅ Passed 357ms
tests/responses-compact-retries.test.ts ✅ Passed 410ms
tests/responses-compact.test.ts ✅ Passed 276ms
tests/responses-create-advanced-stream.test.ts ✅ Passed 251ms
tests/responses-create-advanced.test.ts ✅ Passed 947ms
tests/responses-create-disconnect.test.ts ✅ Passed 948ms
tests/responses-create-errors.test.ts ✅ Passed 349ms
tests/responses-create-malformed-api-responses.test.ts ✅ Passed 295ms
tests/responses-create-retries.test.ts ✅ Passed 244ms
tests/responses-create-stream-failures.test.ts ✅ Passed 241ms
tests/responses-create-stream-timeout.test.ts ✅ Passed 238ms
tests/responses-create-stream-wire.test.ts ✅ Passed 6.118s
tests/responses-create-stream.test.ts ✅ Passed 328ms
tests/responses-create-terminal-states.test.ts ✅ Passed 322ms
tests/responses-create-timeout.test.ts ✅ Passed 229ms
tests/responses-create.test.ts ✅ Passed 592ms
tests/responses-delete.test.ts ✅ Passed 254ms
tests/responses-input-items-errors.test.ts ✅ Passed 530ms
tests/responses-input-items-list.test.ts ✅ Passed 367ms
tests/responses-input-items-options.test.ts ✅ Passed 162ms
tests/responses-input-tokens-count-timeout.test.ts ✅ Passed 190ms
tests/responses-input-tokens-count.test.ts ✅ Passed 348ms
tests/responses-malformed-inputs.test.ts ✅ Passed 4.544s
tests/responses-not-found-errors.test.ts ✅ Passed 295ms
tests/responses-parse.test.ts ✅ Passed 507ms
tests/responses-retrieve-retries.test.ts ✅ Passed 230ms
tests/responses-retrieve.test.ts ✅ Passed 295ms
tests/responses-stored-method-errors.test.ts ✅ Passed 925ms
tests/retry-behavior.test.ts ✅ Passed 3.344s
tests/sdk-error-shape.test.ts ✅ Passed 382ms

View OkTest run #35530489596

SDK merge (648d0f79b3d5) · head (5ec062e0604a) · base (d2969f8efd58) · OkTest (a0be4375e02d)

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 91edcdcbbc

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread api_reference/openapi.transformed.yml
Comment thread api_reference/openapi.transformed.yml
Castiron-Internal-PR: openai/openai-java-internal#126
Castiron-Source-SHA: 0116bd8a1ec0fe164c538d77c4f7c4619fec5a15
Castiron-Public-Base-SHA: d2969f8
@markstuart-oai
markstuart-oai force-pushed the castiron/promotions/pr-126 branch from 91edcdc to 5ec062e Compare September 20, 2026 18:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants