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

.castiron.stats.yml

@@ -1,8 +1,8 @@
 schema_version: 1
-generation_id: 77525871-e2b5-4848-8974-160c8b57938f
-openapi_spec_hash: b6c325f19993092615621b2fa55ace03
-openapi_transformed_spec_hash: 3dae5e7c6a7cc3df593c09d61bc62634
+generation_id: 7f2d67da-e395-4094-9638-e864d6853f0f
+openapi_spec_hash: e004507264375728a48a36cfa571544e
+openapi_transformed_spec_hash: bb7d73817be9bf23b859a5dfd4e15b11
 config_hash: 47b922b06d16fe0e7595c5eacbbb5495
-codegen_sha: 0b77e3fde672b29587a8f518f4e8771e71f0fc01
-codegen_hash: d08e6f35078e51225015ec1dd62823a1b8560f358386eaf64c851cf3f1a87549
-public_codegen_sha: 5e788de0fcea96a56fcd57856e8353fc4c302eb8
+codegen_sha: 4137e96794ab9b83376e52d122e0501c0bfd062e
+codegen_hash: c0b41a4b5fc1e9e31e4293dc058cffa3804fbcaf20f8fffc55674c75d78a9277
+public_codegen_sha: 0b3a2532f3b8a223cb9e61cd0e22eb8cde178b7f

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/resources/beta/responses/responses.ts

@@ -3706,6 +3706,16 @@ export interface BetaResponseError {
   message: string;
 
   misalignment?: BetaResponseError.Misalignment;
+
+  /**
+   * The request parameter associated with the error, or null if none was recorded.
+   */
+  param?: string | null;
+
+  /**
+   * The original error type, or null if it was not recorded.
+   */
+  type?: string | null;
 }
 
 export namespace BetaResponseError {

src/resources/responses/responses.ts

@@ -3271,6 +3271,16 @@ export interface ResponseError {
   message: string;
 
   misalignment?: ResponseError.Misalignment;
+
+  /**
+   * The request parameter associated with the error, or null if none was recorded.
+   */
+  param?: string | null;
+
+  /**
+   * The original error type, or null if it was not recorded.
+   */
+  type?: string | null;
 }
 
 export namespace ResponseError {

src/resources/shared.ts

@@ -27,6 +27,9 @@ export type AllModels =
 /**
  * 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.
@@ -48,6 +51,10 @@ export type AllModels =
  *   "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/resources/videos.ts

@@ -574,6 +574,16 @@ export interface VideoCreateError {
   headers?: { [key: string]: string };
 
   misalignment?: VideoCreateError.Misalignment;
+
+  /**
+   * The request parameter associated with the error, or null if none was recorded.
+   */
+  param?: string | null;
+
+  /**
+   * The original error type, or null if it was not recorded.
+   */
+  type?: string | null;
 }
 
 export namespace VideoCreateError {

tests/lib/responses/error-diagnostics.test.ts

@@ -0,0 +1,49 @@
+import OpenAI from 'openai';
+import { expect, test } from 'vitest';
+
+for (const route of ['responses', 'beta', 'videos']) {
+  for (const errorCase of ['values', 'nulls', 'omitted']) {
+    test(`error diagnostics survive transport: ${route}/${errorCase}`, async () => {
+      const video = route === 'videos';
+      const identifier = video ? 'video_synthetic' : 'resp_synthetic';
+      let requests = 0;
+      const client = new OpenAI({
+        apiKey: 'fake-test-key',
+        baseURL: 'https://example.test',
+        maxRetries: 0,
+        fetch: async (url, init) => {
+          requests += 1;
+          const requestURL = new URL(String(url));
+          expect(requestURL.pathname).toBe(`/${video ? 'videos' : 'responses'}/${identifier}`);
+          expect(requestURL.searchParams.get('beta')).toBe(route === 'beta' ? 'true' : null);
+          expect(init?.method).toBe('GET');
+          return Response.json({
+            id: identifier,
+            error: {
+              code: 'server_error',
+              message: 'Synthetic failure',
+              ...(errorCase === 'omitted'
+                ? {}
+                : {
+                    type: errorCase === 'values' ? 'synthetic_error' : null,
+                    param: errorCase === 'values' ? 'input[0]' : null,
+                  }),
+            },
+          });
+        },
+      });
+      const result = video
+        ? await client.videos.retrieve(identifier)
+        : await (route === 'beta' ? client.beta.responses : client.responses).retrieve(identifier);
+      expect(requests).toBe(1);
+      if (!result.error) {
+        throw new Error('Expected error diagnostics');
+      }
+      const absent = errorCase === 'nulls' ? null : undefined;
+      expect(result.error.type).toBe(errorCase === 'values' ? 'synthetic_error' : absent);
+      expect(result.error.param).toBe(errorCase === 'values' ? 'input[0]' : absent);
+      expect(result.error.code).toBe('server_error');
+      expect(result.error.message).toBe('Synthetic failure');
+    });
+  }
+}