feat(api): add response error diagnostics and model notices

.castiron.stats.yml

@@ -1,8 +1,8 @@
 schema_version: 1
-generation_id: 37557256-538a-4089-92c7-6f39d87dca31
-openapi_spec_hash: b6c325f19993092615621b2fa55ace03
-openapi_transformed_spec_hash: 3dae5e7c6a7cc3df593c09d61bc62634
+generation_id: 7ee6ff28-c1e4-4284-98f1-fa5d0c410e20
+openapi_spec_hash: e004507264375728a48a36cfa571544e
+openapi_transformed_spec_hash: bb7d73817be9bf23b859a5dfd4e15b11
 config_hash: 47b922b06d16fe0e7595c5eacbbb5495
-codegen_sha: 4385b339c0a495b9fcc22b913b174478a699d891
-codegen_hash: 58038e1d56dbd392400609695a51879d4434626f20175b12c5d93d6f77f06388
-public_codegen_sha: 63c09929569758367e2d413b5fa67c005171f861
+codegen_sha: 17b4aa72eb7729595f4446e2310cabba7a743280
+codegen_hash: 38a88497ad58fa758bb623d316d312745e2e820216e6fb5b824185a693bd9abd
+public_codegen_sha: 500f1e917e9dfac7d20c20857dc72ec1aac09686

api_reference/openapi.transformed.yml

@@ -63814,6 +63814,16 @@ components:
               A human-readable description of the error.
           misalignment:
             $ref: '#/components/schemas/MisalignmentErrorDetailsResource'
+          param:
+            anyOf:
+            - type: string
+            - type: 'null'
+            description: The request parameter associated with the error, or null if none was recorded.
+          type:
+            anyOf:
+            - type: string
+            - type: 'null'
+            description: The original error type, or null if it was not recorded.
         required:
         - code
         - message
@@ -79918,6 +79928,16 @@ components:
           x-oaiTypeLabel: map
         misalignment:
           $ref: '#/components/schemas/MisalignmentErrorDetailsResource'
+        param:
+          anyOf:
+          - type: string
+            description: The request parameter associated with the error, or null if none was recorded.
+          - type: 'null'
+        type:
+          anyOf:
+          - type: string
+            description: The original error type, or null if it was not recorded.
+          - type: 'null'
       type: object
       required:
       - code
@@ -101051,6 +101071,16 @@ components:
               A human-readable description of the error.
           misalignment:
             $ref: '#/components/schemas/BetaMisalignmentErrorDetailsResource'
+          param:
+            anyOf:
+            - type: string
+            - type: 'null'
+            description: The request parameter associated with the error, or null if none was recorded.
+          type:
+            anyOf:
+            - type: string
+            - type: 'null'
+            description: The original error type, or null if it was not recorded.
         required:
         - code
         - message
@@ -106551,6 +106581,20 @@ components:
           message: 'Announced shutdown date: 2027-01-20. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.'
         gpt-5.1-mini:
           message: Not a supported model ID. Retained for SDK compatibility.
+        gpt-4.1-2025-04-14:
+          message: 'Announced shutdown date: 2027-01-14. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.'
+        gpt-4.1-mini-2025-04-14:
+          message: 'Announced shutdown date: 2027-01-14. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.'
+        gpt-4o-2024-08-06:
+          message: 'Announced shutdown date: 2027-01-14. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.'
+        gpt-4o-2024-11-20:
+          message: 'Announced shutdown date: 2027-01-14. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.'
+        gpt-4o-mini-2024-07-18:
+          message: 'Announced shutdown date: 2027-01-14. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.'
+        gpt-5.1:
+          message: 'Announced shutdown date: 2027-04-01. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.'
+        gpt-5.4-nano:
+          message: 'Announced shutdown date: 2027-04-01. See https://developers.openai.com/api/docs/deprecations for details and recommended replacements.'
       x-stainless-nominal: false
     LiveBuiltInVoice:
       type: string

src/openai/types/beta/beta_response_error.py

@@ -73,3 +73,9 @@ class BetaResponseError(BaseModel):
     """A human-readable description of the error."""
 
     misalignment: Optional[Misalignment] = None
+
+    param: Optional[str] = None
+    """The request parameter associated with the error, or null if none was recorded."""
+
+    type: Optional[str] = None
+    """The original error type, or null if it was not recorded."""

src/openai/types/responses/response_error.py

@@ -73,3 +73,9 @@ class ResponseError(BaseModel):
     """A human-readable description of the error."""
 
     misalignment: Optional[Misalignment] = None
+
+    param: Optional[str] = None
+    """The request parameter associated with the error, or null if none was recorded."""
+
+    type: Optional[str] = None
+    """The original error type, or null if it was not recorded."""

src/openai/types/shared/chat_model.py

@@ -97,6 +97,9 @@
 ]
 """Deprecated values:
 
+- "gpt-5.4-nano", "gpt-5.1": Announced shutdown date: 2027-04-01. See
+  https://developers.openai.com/api/docs/deprecations for details and
+  recommended replacements.
 - "gpt-5.3-chat-latest", "gpt-5.2-chat-latest": Announced shutdown date:
   2026-08-10. See https://developers.openai.com/api/docs/deprecations for
   details and recommended replacements.
@@ -118,6 +121,10 @@
   "gpt-4-0613", "gpt-3.5-turbo", "gpt-3.5-turbo-0125": Announced shutdown date:
   2026-10-23. See https://developers.openai.com/api/docs/deprecations for
   details and recommended replacements.
+- "gpt-4.1-2025-04-14", "gpt-4.1-mini-2025-04-14", "gpt-4o-2024-11-20",
+  "gpt-4o-2024-08-06", "gpt-4o-mini-2024-07-18": Announced shutdown date:
+  2027-01-14. See https://developers.openai.com/api/docs/deprecations for
+  details and recommended replacements.
 - "o1-preview", "o1-preview-2024-09-12": Announced shutdown date: 2025-07-28.
   See https://developers.openai.com/api/docs/deprecations for details and
   recommended replacements.

src/openai/types/shared_params/chat_model.py

@@ -99,6 +99,9 @@
 ]
 """Deprecated values:
 
+- "gpt-5.4-nano", "gpt-5.1": Announced shutdown date: 2027-04-01. See
+  https://developers.openai.com/api/docs/deprecations for details and
+  recommended replacements.
 - "gpt-5.3-chat-latest", "gpt-5.2-chat-latest": Announced shutdown date:
   2026-08-10. See https://developers.openai.com/api/docs/deprecations for
   details and recommended replacements.
@@ -120,6 +123,10 @@
   "gpt-4-0613", "gpt-3.5-turbo", "gpt-3.5-turbo-0125": Announced shutdown date:
   2026-10-23. See https://developers.openai.com/api/docs/deprecations for
   details and recommended replacements.
+- "gpt-4.1-2025-04-14", "gpt-4.1-mini-2025-04-14", "gpt-4o-2024-11-20",
+  "gpt-4o-2024-08-06", "gpt-4o-mini-2024-07-18": Announced shutdown date:
+  2027-01-14. See https://developers.openai.com/api/docs/deprecations for
+  details and recommended replacements.
 - "o1-preview", "o1-preview-2024-09-12": Announced shutdown date: 2025-07-28.
   See https://developers.openai.com/api/docs/deprecations for details and
   recommended replacements.

src/openai/types/video_create_error.py

@@ -57,3 +57,9 @@ class VideoCreateError(BaseModel):
     """
 
     misalignment: Optional[Misalignment] = None
+
+    param: Optional[str] = None
+    """The request parameter associated with the error, or null if none was recorded."""
+
+    type: Optional[str] = None
+    """The original error type, or null if it was not recorded."""

tests/lib/responses/test_error_diagnostics.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import httpx2
+import pytest
+
+from openai import OpenAI, AsyncOpenAI
+
+
+@pytest.mark.parametrize("route", ["responses", "beta", "videos"])
+@pytest.mark.parametrize("sync", [False, True])
+@pytest.mark.parametrize("shape", ["values", "nulls", "omitted"])
+async def test_error_diagnostics_transport(route: str, sync: bool, shape: str) -> None:
+    error: dict[str, object] = {"code": "server_error", "message": "Synthetic failure"}
+    if shape != "omitted":
+        error.update(
+            type="synthetic_error" if shape == "values" else None, param="input[0]" if shape == "values" else None
+        )
+    video = route == "videos"
+    identifier = "video_synthetic" if video else "resp_synthetic"
+    requests: list[httpx2.Request] = []
+
+    def respond(request: httpx2.Request) -> httpx2.Response:
+        requests.append(request)
+        assert request.method == "GET"
+        assert request.url.path == f"/{'videos' if video else 'responses'}/{identifier}"
+        assert request.url.params.get("beta") == ("true" if route == "beta" else None)
+        return httpx2.Response(200, json={"id": identifier, "error": error})
+
+    transport = httpx2.MockTransport(respond)
+    if sync:
+        with OpenAI(
+            api_key="fake-test-key", base_url="https://example.test", http_client=httpx2.Client(transport=transport)
+        ) as client:
+            if video:
+                # Exercise the retained deprecated API and verify its runtime warning.
+                with pytest.warns(DeprecationWarning, match="Sora API"):
+                    result = client.videos.retrieve(identifier)  # pyright: ignore[reportDeprecated]
+            else:
+                result = (client.beta.responses if route == "beta" else client.responses).retrieve(identifier)
+    else:
+        async with AsyncOpenAI(
+            api_key="fake-test-key",
+            base_url="https://example.test",
+            http_client=httpx2.AsyncClient(transport=transport),
+        ) as client_async:
+            if video:
+                # Exercise the retained deprecated API and verify its runtime warning.
+                with pytest.warns(DeprecationWarning, match="Sora API"):
+                    result = await client_async.videos.retrieve(identifier)  # pyright: ignore[reportDeprecated]
+            else:
+                result = await (client_async.beta.responses if route == "beta" else client_async.responses).retrieve(
+                    identifier
+                )
+    assert len(requests) == 1
+    assert result.error is not None
+    assert result.error.type == ("synthetic_error" if shape == "values" else None)
+    assert result.error.param == ("input[0]" if shape == "values" else None)
+    assert result.error.code == "server_error"
+    assert result.error.message == "Synthetic failure"