chore(api): document fine-tuning and model errors (openai#3964)

## Summary

Clarifies fine-tuning and model error responses while retaining existing
Python behavior.

## Changes

- Describe applicable validation, lookup, permission and rate-limit
errors.
- Preserve existing methods, return types and exception behavior.

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: 9040533e-70f4-4cd8-8f49-a00105025cea
-openapi_spec_hash: 51a93abe82b6f71bdb437dd6a5cb1073
-openapi_transformed_spec_hash: 6e1ff6e06165d5b2e49cbfd336f00c20
+generation_id: 1dd246ed-238d-481d-9649-a93ac4e0d455
+openapi_spec_hash: 91cc2e79b522ef1d5b1d0a7c930b06b2
+openapi_transformed_spec_hash: b081b94fc815ee91ad978e592e233b83
 config_hash: 84cdcc959ee7140cc9a65e9b642c097b
-codegen_sha: 5663a0d22f91cc3d5b3eaa0c03a956c5f48adcfd
+codegen_sha: de6e1f3fdc3337dd65e009deee8a0e6654912a82
 codegen_hash: 67b5ab20d81c80689a8a857466838278fb0d428d48b3261d2479bab43396d589
-public_codegen_sha: 6ce10b315e475749bc0daf4467479a609cdb563d
+public_codegen_sha: ee717eb8a6c8891cc8d8bd1f5af1471d3806b213

api_reference/openapi.transformed.yml

@@ -6598,6 +6598,18 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/RunGraderResponse'
+        '400':
+          description: The grader definition or request is invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: The request rate limit has been exceeded.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
       x-oaiMeta:
         beta: true
         group: graders
@@ -6829,6 +6841,18 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ValidateGraderResponse'
+        '400':
+          description: The grader definition or request is invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: The request rate limit has been exceeded.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
       x-oaiMeta:
         beta: true
         group: graders
@@ -6912,6 +6936,18 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ListFineTuningCheckpointPermissionResponse'
+        '400':
+          description: The query parameters are invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: The request rate limit has been exceeded.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
       x-oaiMeta:
         group: fine-tuning
         examples:
@@ -6971,6 +7007,24 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ListFineTuningCheckpointPermissionResponse'
+        '400':
+          description: The request is invalid or checkpoint permissions cannot be changed for the requested projects or job state.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: The checkpoint or its fine-tuning job was not found, or the checkpoint cannot be shared.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: The request rate limit has been exceeded.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
       x-oaiMeta:
         group: fine-tuning
         examples:
@@ -7028,6 +7082,24 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/DeleteFineTuningCheckpointPermissionResponse'
+        '400':
+          description: The checkpoint permission cannot be removed for the requested project or job state.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: The checkpoint, permission, associated project, or fine-tuning job was not found, or the checkpoint cannot be shared.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: The request rate limit has been exceeded.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
       x-oaiMeta:
         group: fine-tuning
         examples:
@@ -7066,6 +7138,18 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/FineTuningJob'
+        '400':
+          description: The request is invalid or the organization does not meet the requirements to create a fine-tuning job.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: A request or fine-tuning job limit has been exceeded.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
       x-oaiMeta:
         group: fine-tuning
         examples:
@@ -7485,6 +7569,18 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ListPaginatedFineTuningJobsResponse'
+        '400':
+          description: The query parameters are invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: The request rate limit has been exceeded.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
       x-oaiMeta:
         group: fine-tuning
         examples:
@@ -7560,6 +7656,18 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/FineTuningJob'
+        '404':
+          description: The fine-tuning job was not found or is not accessible.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: The request rate limit has been exceeded.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
       x-oaiMeta:
         group: fine-tuning
         examples:
@@ -7643,6 +7751,24 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/FineTuningJob'
+        '400':
+          description: The fine-tuning job cannot be cancelled in its current state.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: The fine-tuning job was not found or is not accessible.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: The request rate limit has been exceeded.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
       x-oaiMeta:
         group: fine-tuning
         examples:
@@ -7716,6 +7842,24 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ListFineTuningJobCheckpointsResponse'
+        '400':
+          description: The query parameters are invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: The fine-tuning job was not found or is not accessible.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: The request rate limit has been exceeded.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
       x-oaiMeta:
         group: fine-tuning
         examples:
@@ -7793,6 +7937,24 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ListFineTuningJobEventsResponse'
+        '400':
+          description: The query parameters are invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: The fine-tuning job was not found or is not accessible.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: The request rate limit has been exceeded.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
       x-oaiMeta:
         group: fine-tuning
         examples:
@@ -7871,6 +8033,24 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/FineTuningJob'
+        '400':
+          description: The fine-tuning job cannot be paused in its current state or does not support pausing.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: The fine-tuning job was not found or is not accessible, or this operation is unavailable.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: The request rate limit has been exceeded.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
       x-oaiMeta:
         group: fine-tuning
         examples:
@@ -7931,6 +8111,24 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/FineTuningJob'
+        '400':
+          description: The fine-tuning job cannot be resumed in its current state or does not support resuming.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: The fine-tuning job was not found or is not accessible, or this operation is unavailable.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: A request or fine-tuning job limit has been exceeded.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
       x-oaiMeta:
         group: fine-tuning
         examples:
@@ -8548,6 +8746,12 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ListModelsResponse'
+        '403':
+          description: The API credential does not have permission to list models.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PermissionErrorResponse'
       x-oaiMeta:
         group: models
         examples:
@@ -8635,6 +8839,18 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Model'
+        '403':
+          description: The API credential does not have permission to retrieve models.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PermissionErrorResponse'
+        '404':
+          description: The model was not found or is not accessible.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
       x-oaiMeta:
         group: models
         examples:
@@ -8700,6 +8916,18 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/DeleteModelResponse'
+        '403':
+          description: Insufficient permissions to delete the model. Model deletion requires the Owner role in the organization and a credential that permits deletion.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PermissionErrorResponse'
+        '404':
+          description: The model was not found, is not accessible, or cannot be deleted through this endpoint.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
       x-oaiMeta:
         group: models
         examples: