docs(swagger): document error responses and reuse Window schema

The OpenAPI spec documented only 200 responses for /allocation, /assets,
and /cloudCost, while the inference cost endpoints documented their 400
and 501 responses. Generated clients therefore assumed the older
endpoints could never fail with 4xx/5xx errors.

Document the error responses each handler actually returns:

- /allocation: 400 (invalid window/aggregate/step/accumulate), 500
- /assets: 400 (invalid window), 500
- /cloudCost: 400, 500, and 501 (query service unavailable; note that
  the route is not registered at all when CLOUD_COST_ENABLED is false)
- /inferenceCost/total and /inferenceCost/timeseries: add the 500 the
  handlers return on query failure (400/501 were already documented)

501 is intentionally not added to /allocation and /assets because those
handlers never return it.

Also replace the inline window object definitions in the Allocation and
Asset schemas with $ref to the canonical #/components/schemas/Window
component, which the other schemas already reference.

Fixes #3923

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: Claude <noreply@anthropic.com>

docs/swagger.json

@@ -78,6 +78,12 @@
                 }
               }
             }
+          },
+          "400": {
+            "description": "Bad request — missing or invalid parameters (e.g. `window`, `aggregate`, `step`, `accumulate`)"
+          },
+          "500": {
+            "description": "Internal server error — the allocation query failed"
           }
         }
       }
@@ -106,6 +112,12 @@
                 }
               }
             }
+          },
+          "400": {
+            "description": "Bad request — missing or invalid `window` parameter"
+          },
+          "500": {
+            "description": "Internal server error — computing or filtering assets failed"
           }
         }
       }
@@ -134,6 +146,15 @@
                 }
               }
             }
+          },
+          "400": {
+            "description": "Bad request — missing or invalid parameters"
+          },
+          "500": {
+            "description": "Internal server error — the cloud cost query failed"
+          },
+          "501": {
+            "description": "Cloud cost query service is not available. Note: when `CLOUD_COST_ENABLED` is not set to `true` this route is not registered at all and requests return 404."
           }
         }
       }
@@ -215,6 +236,9 @@
           "400": {
             "description": "Bad request — missing or invalid parameters"
           },
+          "500": {
+            "description": "Internal server error — the inference cost query failed"
+          },
           "501": {
             "description": "Inference cost tracking is not enabled (`INFERENCE_COST_ENABLED` is not set to `true`)"
           }
@@ -296,6 +320,9 @@
           "400": {
             "description": "Bad request — missing or invalid parameters (including missing `accumulate`)"
           },
+          "500": {
+            "description": "Internal server error — the inference cost query failed"
+          },
           "501": {
             "description": "Inference cost tracking is not enabled (`INFERENCE_COST_ENABLED` is not set to `true`)"
           }
@@ -362,17 +389,7 @@
             "type": "number"
           },
           "window": {
-            "type": "object",
-            "properties": {
-              "start": {
-                "type": "string",
-                "format": "date-time"
-              },
-              "end": {
-                "type": "string",
-                "format": "date-time"
-              }
-            }
+            "$ref": "#/components/schemas/Window"
           },
           "properties": {
             "type": "object",
@@ -418,17 +435,7 @@
             "type": "string"
           },
           "window": {
-            "type": "object",
-            "properties": {
-              "start": {
-                "type": "string",
-                "format": "date-time"
-              },
-              "end": {
-                "type": "string",
-                "format": "date-time"
-              }
-            }
+            "$ref": "#/components/schemas/Window"
           }
         }
       },