Azure Cost Management Forecast API 错误处理完全指南：状态码、校验错误与重试策略

本篇技术指南聚焦 autoskills 仓库中 azure-cost 技能 的 Cost Forecast（成本预测）工作流，系统讲解 Microsoft Cost Management Forecast API（api-version=2023-11-01）的完整错误处理体系。读完本文，你将掌握 400/401/403/404/424/429/503 各状态码的成因与修复路径、7 类请求体校验错误码的精确含义、预测模型特有的降级场景（如训练数据不足），以及基于 x-ms-ratelimit-microsoft.costmanagement-*-retry-after 响应头的安全重试策略。

一、Forecast API 错误处理在技能体系中的定位

在 autoskills 的 azure-cost 技能中，成本管理被拆分为三个独立工作流：历史成本查询（cost-query）、成本优化（cost-optimization）和成本预测（cost-forecast）。本文所讲解的错误处理文档即位于预测工作流目录中，是 Forecast 工作流 的"错误处理"章节的完整展开版。

与 Query API 错误处理 相比，Forecast API 的错误面更窄但更特殊：它既要处理通用 HTTP 状态码，又要处理预测专属的校验错误（如 CantForecastOnThePast、DontContainIncludeActualCostWhileIncludeFreshPartialCost），还要区分"预测不可用"这类非错误的合法响应。

二、HTTP 状态码总览

状态码	错误	典型成因	修复方式
400	Bad Request	请求体非法、缺少 dataset、日期全部落在过去、字段依赖组合非法	检查请求体结构；确保 to 日期在未来；核对 includeActualCost/includeFreshPartialCost 的依赖关系
401	Unauthorized	认证失败——令牌缺失或过期	通过 az login 重新认证或刷新访问令牌
403	Forbidden	对目标作用域权限不足	确保身份在目标作用域上拥有 Cost Management Reader 角色（或更高）
404	Not Found	作用域 URL 非法——订阅、资源组或账单账户不存在	核对作用域 URL 路径与资源 ID 是否正确
424	Failed Dependency	训练数据不佳——预测模型无法计算预测结果	若 includeActualCost=true 则回退为仅返回实际成本；否则建议改用 Cost Query 工作流 获取历史数据
429	Too Many Requests	触发限流——QPU、实体或租户配额超限	检查所有 x-ms-ratelimit-microsoft.costmanagement-*-retry-after 响应头（qpu、entity、tenant），等待最长的等待时长后再重试
503	Service Unavailable	服务临时故障	查看 Azure 状态页确认服务健康状态

2.1 与 Query API 状态码的对照

参照 Cost Query 错误处理，两个 API 的 401/403/404/429/503 语义完全一致，核心差异集中在 400 与 424：

• 400 的来源不同：Query API 的 400 多源于不支持的维度、日期范围超限、过滤器结构非法；Forecast API 的 400 则聚焦于预测专属的字段依赖（详见下文校验错误码）。
• 424 是 Forecast 专属：Query API 没有该状态码，它是预测模型训练数据问题的信号。

三、校验错误码参考（Validation Error Reference）

当 Forecast API 返回 400 时，响应中的 error.code 字段会给出机器可读的精确错误码。完整参考如下：

错误码	描述	修复方式
EmptyForecastRequestBody	请求体为空或为 null	提供包含 type、timeframe、timePeriod、dataset 的完整请求体
InvalidForecastRequestBody	请求体 JSON 结构非法	检查 JSON 语法——核对花括号、逗号与字段名
DontContainsDataSet	请求体缺少 dataset 字段	添加包含 granularity 和 aggregation 的 dataset 对象
DontContainsValidTimeRangeWhileContainsPeriod	timePeriod 存在但 from 或 to 非法	确保 from 和 to 都是合法的 ISO 8601 日期时间字符串
DontContainsValidTimeRangeWhileMonthlyAndIncludeCost	月粒度且 includeActualCost=true，但缺少合法 timePeriod	添加带合法 from、to 日期的显式 timePeriod
DontContainIncludeActualCostWhileIncludeFreshPartialCost	includeFreshPartialCost=true 但未设置 includeActualCost=true	设置 includeActualCost=true，或把 includeFreshPartialCost 改为 false
CantForecastOnThePast	from 与 to 日期都在过去	确保 to 日期在未来

3.1 字段依赖错误的前置背景

理解 DontContainsValidTimeRangeWhileMonthlyAndIncludeCost 与 DontContainIncludeActualCostWhileIncludeFreshPartialCost 这两个错误，需要先掌握 Forecast 请求体结构 中的两条硬性依赖：

• includeActualCost：默认 true，用于在预测结果旁附带历史实际成本行（从 from 日期到今日）；
• includeFreshPartialCost：默认 true，用于包含最近几天的部分（未完全结算的）成本数据，强制要求 includeActualCost=true。

在 预测护栏文档 中同样强调：设置 includeFreshPartialCost=true 而缺少 includeActualCost=true 会直接产生 DontContainIncludeActualCostWhileIncludeFreshPartialCost，建议始终显式同时设置这两个字段，而不是依赖默认值。

四、预测专属场景（Forecast-Specific Scenarios）

预测 API 有一些"看似报错、实为合法响应"的特殊场景，必须与真实错误区分开：

场景	响应形态	处理动作
"Forecast is unavailable for the specified time period"	合法响应，数据行为 null/空	不是错误——历史数据不足（少于 28 天）。建议改用 Cost Query 工作流 获取已有历史数据
"Can't forecast on the past"	400 错误，错误码 CantForecastOnThePast	确保 to 日期在未来
训练数据不佳	424 Failed Dependency	若 includeActualCost=true，响应自动回退为仅返回实际成本数据；否则建议用 Cost Query 工作流 获取历史数据
解析异常	400 Bad Request	检查 JSON 格式——核对花括号、引号、逗号与字段类型

4.1 为什么"预测不可用"不是错误

结合 预测护栏文档 可知，该响应的触发条件包括：响应无数据行、作用域成本历史少于 28 天、或作用域从未产生过任何成本数据。其背后是模型的训练数据要求：

• 最少需要 4 周（28 天）历史成本数据；
• 优选训练窗口为最多 3 个月历史；
• 账单数据到达的延迟容忍期为 2 天；
• 新建订阅（不足 28 天历史）无法生成预测。

出现该响应时不应重试（重试无法凭空产生训练数据），正确做法是引导用户使用 Cost Query 工作流 拉取已有历史数据。

4.2 424 的回退机制细节

424（训练数据不佳）并非不可恢复，其行为取决于请求中的 includeActualCost 取值：

• includeActualCost=true：API 自动回退，响应中只包含实际成本数据（CostStatus 全部为 Actual）；
• includeActualCost=false：无法回退，此时应建议用户改用 Cost Query 工作流获取历史数据。

需要说明的是，从当前仓库文档可以确认该回退行为的存在与前提条件，但响应行的具体组织方式取决于服务端实现，本文不做进一步推断。

五、重试策略（Retry Strategy）

状态码	是否重试	策略
429	✅ 是	检查响应中所有 x-ms-ratelimit-microsoft.costmanagement-*-retry-after 响应头（qpu-retry-after、entity-retry-after、tenant-retry-after），取最长值，在该时长完全过去之前不要重试。最多重试 3 次
400	❌ 否	根据校验错误码修复请求体
401	❌ 否	重新认证——令牌缺失或过期
403	❌ 否	在目标作用域授予 Cost Management Reader 角色
404	❌ 否	修复作用域 URL——核对订阅、资源组或账单账户 ID
424	❌ 否	训练数据问题——重试无济于事。回退到实际成本或用 Cost Query 工作流
503	❌ 否	不要重试。查看 Azure 状态页确认服务健康

⚠️ 警告：除 429 外，不要重试任何错误。 其余错误都表明请求本身存在问题，必须在重新发起请求前修复。

5.1 429 限流的深入处理

429 是唯一允许自动重试的状态码，但处理时需遵循严格的纪律。依据 预测护栏文档，Forecast API 与 Query API 共享相同的限流阈值：

限制维度	阈值
每用户	每分钟 20 个请求
每作用域	每分钟 4 个请求
每租户	每 10 秒 12 个请求、每分钟 60 个、每小时 600 个
每客户端类型	每分钟 2,000 个请求

其中每作用域限制（每分钟 4 个请求）最为严格——对同一订阅、资源组或账单账户的连续查询共享该额度。因此在 azure-cost 技能的主 SKILL.md 最佳实践 中，也明确要求：收到 429 时检查全部三个 retry-after 响应头，取最长值等待，等待时长完全过去前不得重试。

响应头名称与含义如下：

响应头	描述
x-ms-ratelimit-microsoft.costmanagement-qpu-retry-after	基于 QPU（查询处理单元）的等待秒数
x-ms-ratelimit-microsoft.costmanagement-entity-retry-after	实体/作用域级节流等待秒数
x-ms-ratelimit-microsoft.costmanagement-tenant-retry-after	租户级节流等待秒数

关键纪律：429 响应可能同时返回多个 retry-after 头，必须取最大值等待；提前重试会被拒绝，并可能延长节流窗口。

5.2 错误响应结构与定位方法

从 Cost Query 错误处理 可以确认，Cost Management 系列 API 的错误响应遵循统一的 JSON 结构，Forecast API 同样适用：

{
  "error": {
    "code": "<error-code>",
    "message": "<human-readable-error-message>",
    "details": [
      {
        "code": "<detail-code>",
        "message": "<detail-message>"
      }
    ]
  }
}

字段	描述
error.code	机器可读错误码（如 BadRequest、CantForecastOnThePast）
error.message	人类可读的错误描述
error.details	可选数组，包含更具体的错误信息对象

收到 400 时，应优先读取 error.code 与上文"校验错误码参考"表对照定位，而不是仅依赖人类可读的 message 文本。

六、避免错误的请求体构建实践

错误处理的最佳策略是让错误不发生。结合 Forecast 请求体结构 与 预测示例，一个规范的预测请求应包含：

{
  "type": "ActualCost",
  "timeframe": "Custom",
  "timePeriod": {
    "from": "2024-01-01T00:00:00Z",
    "to": "2024-03-31T00:00:00Z"
  },
  "dataset": {
    "granularity": "Daily",
    "aggregation": {
      "totalCost": {
        "name": "Cost",
        "function": "Sum"
      }
    },
    "sorting": [
      {
        "direction": "Ascending",
        "name": "UsageDate"
      }
    ],
    "filter": {
      "dimensions": {
        "name": "ResourceGroupName",
        "operator": "In",
        "values": ["my-resource-group"]
      }
    }
  },
  "includeActualCost": true,
  "includeFreshPartialCost": true
}

对应 工作流文档 中的关键规则，构建请求时需同步校验以下约束，从源头规避 400/424：

1. to 日期必须在未来——整个日期区间都落在过去会触发 CantForecastOnThePast；
2. from 可以落在过去——响应会包含"从 from 到今日"的实际成本行与"从今日到 to"的预测行；
3. 至少 28 天历史成本数据——不足时预测模型无法计算，触发"预测不可用"或 424；
4. 最大预测窗口 10 年；
5. 分组（grouping）不被支持——请求体中不得出现该字段，需要按资源组/服务分组的预测需求应改用 Cost Query 工作流；
6. 响应行数上限约 40 行——日粒度下"30 天实际 + 30 天预测 = 60 行"会超限，日粒度建议预测窗口控制在 2～3 周，更长期限改用月粒度。

6.1 各作用域的请求 URL 模板

错误处理中的 404 修复，本质上是对作用域 URL 的核对。预测示例 给出了三种常用作用域的路径模板（均为 path-only，需自行拼接 ?api-version=2023-11-01）：

作用域	URL 路径模板
订阅	/subscriptions/<subscription-id>/providers/Microsoft.CostManagement/forecast
资源组	/subscriptions/<subscription-id>/resourceGroups/<rg-name>/providers/Microsoft.CostManagement/forecast
账单账户	/providers/Microsoft.Billing/billingAccounts/<id>/providers/Microsoft.CostManagement/forecast

若收到 404，按此模板逐段核对订阅 ID、资源组名或账单账户 ID 是否正确、资源是否存在。

七、在 autoskills 技能体系中实践错误处理

autoskills 仓库通过 技能注册表 与 skills-map.ts 管理所有技能，azure-cost 技能本身以 SKILL.md 为入口。当 Agent 处理"预测未来成本""月底账单预估"类请求时，会按 路由表 进入 Cost Forecast 工作流，其中第 7 步"解释响应"与"错误处理"环节即依赖本文所述规则。

一个完整的错误处理决策路径可以归纳为：

1. 收到非 200 响应，先读取 error.code；
2. 对照状态码表定位大类：400 → 查校验错误码表；401 → 重新认证；403 → 检查 RBAC 角色；404 → 核对作用域 URL；424 → 判定为训练数据问题；429 → 走限流重试流程；503 → 查看服务健康状态；
3. 确认是否"预测不可用"合法响应（空行 + 提示信息）——此时不做任何重试，直接引导 Cost Query 工作流；
4. 唯一可自动重试的是 429，且必须等待全部 retry-after 头中的最大值，最多重试 3 次；
5. 每次修复后重新发起请求前，用第六节的请求体构建规则做一次自查。

八、要点速查

• 唯一可重试的状态码是 429，其余错误都必须先修复再重试；
• 429 处理口诀：读全三个 x-ms-ratelimit-microsoft.costmanagement-*-retry-after 头，取最长值，等满再试，最多 3 次；
• "Forecast is unavailable"不是错误，而是历史数据不足（< 28 天）的合法响应，应改用 Cost Query 工作流；
• 两个高频字段依赖错误：DontContainsValidTimeRangeWhileMonthlyAndIncludeCost（月粒度 + includeActualCost 需显式 timePeriod）与 DontContainIncludeActualCostWhileIncludeFreshPartialCost（includeFreshPartialCost 依赖 includeActualCost=true）；
• CantForecastOnThePast 的唯一修复方式是让 to 日期落在未来；
• 404 的修复入口是作用域 URL 模板，而非请求体；
• 构建请求前用六大约束自查（未来 to、28 天历史、10 年上限、禁分组、40 行上限、显式双 include 字段），可规避绝大多数 400/424。