1# Forecast API Guardrails
2 
3Detailed guardrails derived from CCM-LUX getForecastData and CCM-UX-MIDDLEWARE Forecaster.
4 
5## Time Period Validation
6 
7| Rule | Detail |
8|---|---|
9| `to` date must be in the future | `numberOfDaysToForecast` must be > 0. Entirely past date ranges return a `CantForecastOnThePast` error. |
10| `from` can be in the past | When `from` is in the past, the response includes actual costs from `from` to today and forecast costs from today to `to`. |
11| Both dates must be valid | When `timePeriod` is present, both `from` and `to` must be valid parseable ISO 8601 datetime strings. |
12| Monthly + includeActualCost | Monthly granularity with `includeActualCost=true` requires an explicit `timePeriod` with valid `from` and `to` dates. Omitting it produces `DontContainsValidTimeRangeWhileMonthlyAndIncludeCost`. |
13| Maximum forecast period | 10 years maximum forecast window. |
14 
15> ⚠️ **Warning:** If both `from` and `to` are in the past, the API returns `CantForecastOnThePast`. At least the `to` date must be in the future.
16 
17## Training Data Requirements
18 
19| Requirement | Value |
20|---|---|
21| Minimum historical data | 4 weeks (28 days) of cost data |
22| Preferred training window | Up to 3 months of history |
23| Late arrival tolerance | 2 days for billing data to arrive |
24| New subscriptions (< 28 days) | Forecast unavailable |
25 
26> ⚠️ **Warning:** New subscriptions with fewer than 28 days of cost history cannot generate forecasts. Suggest using **the Cost Query workflow (Part 1)** to retrieve available historical data instead.
27 
28## Grouping Restriction
29 
30| Aspect | Detail |
31|---|---|
32| Grouping support | ❌ **Not supported** |
33| API limitation | This is a hard limitation of the Forecast API. The `grouping` field is not accepted in the request body. |
34| Workaround | If the user requests a grouped forecast (e.g., forecast by resource group or service), inform them that grouping is not supported for forecasts. Suggest querying historical data with grouping using **the Cost Query workflow (Part 1)** instead. |
35 
36> ⚠️ **Warning:** Even when using **the Cost Query workflow (Part 1)** for grouped historical data, `ResourceId` grouping is only supported at subscription scope and below. It is not supported at billing account, management group, or higher scopes.
37 
38## Response Row Limit
39 
40| Constraint | Detail |
41|---|---|
42| Maximum rows | 40 rows per forecast response |
43| Daily example | 30 actual days + 30 forecast days = 60 rows → **exceeds limit** |
44| Recommendation | For daily granularity, keep forecast period to ~2–3 weeks |
45| Longer periods | Use monthly granularity to stay within the row limit |
46 
47> 💡 **Tip:** If the user needs a daily forecast for more than 2–3 weeks, consider splitting the request into smaller time windows or switching to monthly granularity.
48 
49## includeActualCost / includeFreshPartialCost
50 
51| Field | Default | Dependency |
52|---|---|---|
53| `includeActualCost` | `true` | None |
54| `includeFreshPartialCost` | `true` | **Requires `includeActualCost=true`** |
55 
56> ⚠️ **Warning:** Setting `includeFreshPartialCost=true` without `includeActualCost=true` produces validation error `DontContainIncludeActualCostWhileIncludeFreshPartialCost`. Always set both fields explicitly.
57 
58## Forecast Availability
59 
60The API returns "Forecast is unavailable for the specified time period" when:
61 
62| Condition | Detail |
63|---|---|
64| Null/empty response rows | Response has no data rows |
65| Insufficient training data | Scope has fewer than 28 days of cost history |
66| No cost history | Scope has never had any cost data |
67 
68> ⚠️ **Warning:** This is **not an error** — it is a valid response indicating the forecast model cannot generate predictions. Do not retry. Instead, suggest using **the Cost Query workflow (Part 1)** to retrieve whatever historical data is available.
69 
70## Rate Limiting
71 
72### Rate Limit Thresholds
73 
74The Forecast API shares the same rate limits as the Cost Query API:
75 
76| Limit | Value |
77|-------|-------|
78| Per User | 20 requests per minute |
79| Per Scope | 4 requests per minute |
80| Per Tenant | 12 requests per 10 seconds, 60 requests per minute, 600 requests per hour |
81| Per Client Type | 2,000 requests per minute |
82 
83> ⚠️ **Warning:** The **per-scope limit (4 requests/minute)** is the most restrictive. Sequential queries to the same subscription, resource group, or billing account share this limit.
84 
85### Rate Limit Headers
86 
87| Header | Description |
88|---|---|
89| `x-ms-ratelimit-microsoft.costmanagement-qpu-retry-after` | Seconds to wait before retrying (QPU-based) |
90| `x-ms-ratelimit-microsoft.costmanagement-entity-retry-after` | Seconds to wait for entity/scope-level throttle |
91| `x-ms-ratelimit-microsoft.costmanagement-tenant-retry-after` | Seconds to wait for tenant-level throttle |
92 
93### Handling 429 Responses
94 
95On a 429 response, check **all** retry-after headers present in the response. Multiple headers may be returned simultaneously. Take the **maximum** value and **do NOT retry until that duration has fully elapsed.**
96 
97> ⚠️ **Warning:** Do not retry before the retry-after duration has elapsed. Premature retries will be rejected and may extend the throttling period.
98