# 400 错误请求：API 版本标头 'X-API-Version' 是必需的，且必须为有效的语义化版本

- **ID:** `api/rest-api-version-mismatch-header`
- **领域:** api
- **类别:** config_error
- **验证级别:** ai_generated
- **修复率:** 95%

## 根因

客户端未在请求中包含必需的 'X-API-Version' 标头，或者该值不符合语义化版本控制（例如，'2.0' 而非 '2.0.0'）。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| REST API best practices 2023+ | active | — | — |
| Spring Boot 3.x | active | — | — |
| FastAPI 0.100+ | active | — | — |
| Express.js 4.x | active | — | — |

## 解决方案

1. ```
   Add the 'X-API-Version' header with a valid semver value. Example in cURL:
curl -H 'X-API-Version: 2.0.0' https://api.example.com/resource
   ```
2. ```
   Check the API documentation for the exact version string required (e.g., '1.0.0', '2.1.3').
   ```
3. ```
   If using an HTTP client library, set default headers. Example in Python requests:
headers = {'X-API-Version': '2.0.0'}
response = requests.get('https://api.example.com/resource', headers=headers)
   ```

## 无效尝试

- **** — The server strictly requires the header; omitting it results in a 400 error. (90% 失败率)
- **** — The server expects a full semver string (e.g., '2.0.0'); partial versions are rejected. (70% 失败率)
- **** — The server specifically looks for 'X-API-Version'; other headers are ignored. (95% 失败率)