> 完整文档索引见 [llms.txt](https://docs.wanduanapi.com/llms.txt)。本站每个文档页均提供 Markdown 镜像；当前页面的 Markdown 版本见 [此处](https://docs.wanduanapi.com/problems.md)。

# 错误说明

REST 错误响应遵循 RFC 9457，响应媒体类型为 `application/problem+json`（HTTP `Content-Type`），除状态码外还包含可执行的修复指引。`type` 是问题的主标识，本站每个 `type` 都有独立的说明页；`code` 是稳定的短码，便于程序内部分支处理。建议优先按 `type` 理解错误，再按 `code` 做本地映射。

```json
{
  "type": "https://docs.wanduanapi.com/problems/invalid-date-format",
  "title": "日期格式无效",
  "status": 400,
  "detail": "日期必须使用 ISO 8601 yyyy-MM-dd 格式",
  "instance": "/v1/china-calendar/dates/2026-10-0",
  "code": "INVALID_DATE_FORMAT",
  "requestId": "f4935479-81fe-406f-b9d8-a4b67d6d6399"
}
```

- `requestId`：一次请求的唯一定位符，反馈问题时附上它能加速排查；
- `instance`：触发问题的请求路径；
- 问题页只说明公开的修复方式，不披露服务内部实现。

## 错误类型一览

| 问题类型 | code | HTTP 状态 |
| --- | --- | --- |
| [日期格式无效](./invalid-date-format.md) | `INVALID_DATE_FORMAT` | 400 |
| [缺少必填参数](./missing-parameter.md) | `MISSING_PARAMETER` | 400 |
| [日期区间无效](./invalid-date-range.md) | `INVALID_DATE_RANGE` | 400 |
| [日期区间跨度过大](./date-range-too-large.md) | `DATE_RANGE_TOO_LARGE` | 400 |
| [日期超出支持范围](./date-out-of-supported-range.md) | `DATE_OUT_OF_SUPPORTED_RANGE` | 400 |
| [日历数据暂时不可用](./calendar-data-unavailable.md) | `CALENDAR_DATA_UNAVAILABLE` | 503 |
| [资源不存在](./resource-not-found.md) | `RESOURCE_NOT_FOUND` | 404 |
| [方法不允许](./method-not-allowed.md) | `METHOD_NOT_ALLOWED` | 405 |
| [服务内部错误](./internal-error.md) | `INTERNAL_ERROR` | 500 |

## 使用注意

:::tip
如果生产环境迁移域名，历史 `type` URI 仍会持续可访问。不要将 URI 字符串改写为新域名——它是稳定标识，不是普通链接。
:::

MCP 工具的错误不使用 Problem Details：工具返回 `isError=true`，文本以 `CODE:` 开头，`CODE` 与 REST 的 `code` 语义一致。另需注意，年度安排未发布不是错误，会以正常的 `UNKNOWN` 业务结果返回。