chore(api): document batch error responses (openai#3961)

## Summary

Documents applicable Batch API errors while preserving Python exception
behavior.

## Changes

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

Co-authored-by: markstuart-oai <323302876+markstuart-oai@users.noreply.github.com>

Author: markstuart-oai

.castiron.stats.yml

@@ -1,8 +1,8 @@
 schema_version: 1
-generation_id: bbcf5fb4-a54f-48d7-9c24-772776477085
-openapi_spec_hash: 0e4e2f7dffefdf9af4ba091f557e3698
-openapi_transformed_spec_hash: 289efd507762e0572ba21c2b46935826
+generation_id: bf7a8dff-eafb-43e0-873c-86458c45c4bc
+openapi_spec_hash: 0ec6a7e693cd01f26722c3dab19fc122
+openapi_transformed_spec_hash: f0b54f1f631dbd006b7768595bcda2d4
 config_hash: 84cdcc959ee7140cc9a65e9b642c097b
-codegen_sha: 89568c51f375a47f1d3156069016495765eeb70f
+codegen_sha: d04e68695b3ce0aedd210db03d3a02ec740a3cef
 codegen_hash: 67b5ab20d81c80689a8a857466838278fb0d428d48b3261d2479bab43396d589
-public_codegen_sha: adc070c132abc2bdd81fd8ef5c4b75925ea0a02c
+public_codegen_sha: 00b2059284b62aea18c2360ad9cd3ee65a9c12e5

api_reference/openapi.transformed.yml

@@ -1540,6 +1540,30 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Batch'
+        '400':
+          description: The request is invalid or the account cannot create a batch.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: The request was rejected because a rate limit was exceeded.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: An internal error prevented the batch from being created.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '503':
+          description: The batch could not be created because the service is temporarily unavailable.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
       x-oaiMeta:
         group: batch
         examples:
@@ -1637,6 +1661,24 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ListBatchesResponse'
+        '400':
+          description: Invalid pagination parameters.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: No batch was found with the specified pagination cursor.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: The request was rejected because a rate limit was exceeded.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
       x-oaiMeta:
         group: batch
         examples:
@@ -1724,6 +1766,24 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Batch'
+        '400':
+          description: Invalid batch ID.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: No batch was found with the specified ID.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: The request was rejected because a rate limit was exceeded.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
       x-oaiMeta:
         group: batch
         examples:
@@ -1800,6 +1860,30 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Batch'
+        '400':
+          description: Invalid batch ID.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: No batch was found with the specified ID.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '409':
+          description: The batch's current status does not allow cancellation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: The request was rejected because a rate limit was exceeded.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
       x-oaiMeta:
         group: batch
         examples:
@@ -66973,6 +67057,36 @@ components:
             "type": "safety.warning_issued",
             "data": {"id": "C-abc123"}
           }
+    _MisalignmentErrorType:
+      anyOf:
+      - type: string
+      - type: string
+        enum:
+        - potentially_unintended_data_transfer
+        - potentially_unintended_data_access
+        - potentially_unintended_destructive_activity
+        - other
+    _MisalignmentSteer:
+      properties:
+        message:
+          type: string
+          description: The public continuation instruction.
+      type: object
+      required:
+      - message
+    MisalignmentErrorDetailsResource:
+      properties:
+        error_type:
+          $ref: '#/components/schemas/_MisalignmentErrorType'
+          description: An optional classification; clients must accept additional values.
+        detailed_explanation:
+          type: string
+          description: The public explanation for this block.
+        steer:
+          $ref: '#/components/schemas/_MisalignmentSteer'
+          description: An optional public continuation instruction.
+      type: object
+      required: []
     ModerationInputType:
       type: string
       enum:
@@ -70449,36 +70563,6 @@ components:
       - object
       - metadata
       - created_at
-    _MisalignmentErrorType:
-      anyOf:
-      - type: string
-      - type: string
-        enum:
-        - potentially_unintended_data_transfer
-        - potentially_unintended_data_access
-        - potentially_unintended_destructive_activity
-        - other
-    _MisalignmentSteer:
-      properties:
-        message:
-          type: string
-          description: The public continuation instruction.
-      type: object
-      required:
-      - message
-    MisalignmentErrorDetailsResource:
-      properties:
-        error_type:
-          $ref: '#/components/schemas/_MisalignmentErrorType'
-          description: An optional classification; clients must accept additional values.
-        detailed_explanation:
-          type: string
-          description: The public explanation for this block.
-        steer:
-          $ref: '#/components/schemas/_MisalignmentSteer'
-          description: An optional public continuation instruction.
-      type: object
-      required: []
     ImageGenOutputTokensDetails:
       properties:
         image_tokens: