适用场景
当你的应用需要获取全国 3 万+ 城市的实时天气、未来 7 天预报、24 小时逐小时趋势、空气质量指数（AQI）、9 项生活指数（穿衣、防晒、限行等）以及气象预警与农历信息时，墨迹天气 API 是一个一站式的选择。它支持按城市名或内部 ID 查询，也提供历史天气追溯功能。然而，在实际接入过程中，由于参数拼写错误、查询模式混用、鉴权配置不当等原因，开发者可能会遇到各种返回错误。本文将从实战角度出发，系统梳理这些常见问题及其排查方法。
接口能力边界
在开始排错前，你需要理解该接口的核心规则：
- 请求方法：GET
- 基准地址：
https://v1.apizero.cn/api/moji-weather - QPS 限制：5 次/秒，超出后返回 429 状态码
- 缓存策略：
- 实况数据：缓存 5 分钟
- 当月历史：缓存 30 分钟
- 过去月份历史：缓存 24 小时
- 数据用途：由墨迹天气官方提供，不能用于农业、保险、航运、防灾等专业决策场景
所有返回数据均以 JSON 格式包裹在code/msg/data结构中。code: 0表示成功，非零值表示错误。
参数与鉴权
请求支持两种鉴权方式（二选一无需同时使用）：
- Header 方式：添加
Authorization: YOUR_API_KEY - Query 方式：添加
?api_key=YOUR_API_KEY（建议使用 Header，更规范）
核心 Query 参数：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
city | string | 否 | 城市中文名，支持模糊匹配，与id二选一 |
id | number | 否 | 城市 internal_id，优先精确匹配 |
op | string | 否 | 取值search/history，缺省为实况 |
keyword | string | 配合op=search | 城市关键字，支持中文、拼音、首字母 |
limit | number | 配合op=search | 返回条数，1~50，默认 20 |
day | string | 配合op=history | 日期，格式 YYYY-MM-DD / MM-DD / DD，需额外提供month |
month | string | 配合op=history | 月份 YYYYMM，可查整月数据 |
请求示例（curl）
获取实况天气：
curl -sS \ -X GET \ -H "Authorization: YOUR_API_KEY" \ "https://v1.apizero.cn/api/moji-weather?city=北京"按 internal_id 查询（更快）：
curl -sS \ -X GET \ -H "Authorization: YOUR_API_KEY" \ "https://v1.apizero.cn/api/moji-weather?id=33"搜索城市列表获取 id：
curl -sS \ -X GET \ -H "Authorization: YOUR_API_KEY" \ "https://v1.apizero.cn/api/moji-weather?op=search&keyword=大化&limit=5"查询历史天气：
curl -sS \ -X GET \ -H "Authorization: YOUR_API_KEY" \ "https://v1.apizero.cn/api/moji-weather?op=history&city=北京&day=2026-05-12"响应数据解读
成功时返回如下结构（已精简）：
{ "code": 0, "msg": "成功", "data": { "_cached": false, "city": { "id": 1205, "name": "大化瑶族自治县", "parent": "广西壮族自治区", "pinyin": "dahuayaozuzizhixian", "timezone": 8 }, "condition": { "temperature": 32, "condition": "多云", "humidity": 62, "wind_dir": "南风", "wind_level": 3 }, "aqi": { "value": 29, "level": 1, "description": "优" }, "forecast_day": [ /* 7 天预报 */ ], "forecast_hour": [ /* 24 小时 */ ], "index": [ /* 生活指数 */ ], "summary": "大化瑶族自治县，多云，32℃，南风3级，空气优。" } }注意_cached字段标识本次是否命中缓存。condition中的lunar_date为农历日期。
常见错误与排错
以下列出接入过程中的高频问题，按错误来源分类。
1. 城市参数错误：city 与 id 冲突或都缺失
现象：返回code: 400，msg: "参数错误，city 与 id 必填其一"（示意）
原因：请求未提供city也未提供id，或同时提供了两者但值不一致。
排查步骤：
- 检查请求 URL 中是否包含
?city=xxx或?id=xxx - 确认城市名无编码问题（如空格被编码为
%20仍可接受，但优先使用正确中文） - 如果同时使用
city和id，API 会优先使用id，但建议只传一个以避免混淆
2. 无效的 internal_id
现象：返回code: 404，msg: "未找到该城市"，且data为空
原因：传入的id在数据库中不存在，可能从旧版本或第三方复制而来。
排查步骤：
- 先用
op=search&keyword=城市名获取正确的id - 注意
id是 number 类型，不要用字符串 "33" 导致类型不匹配（但 API 通常会自动转换，推荐仍传 number） id是内部整数，不同环境可能不同，请以当前接口搜索为准
3. 鉴权失败
现象：返回 HTTP 401 或 403，响应 JSON 中code: 10001（示意），msg: "无效的 API Key"
原因：
- 未提供
AuthorizationHeader 或api_keyQuery 参数 - API Key 过期、被禁用或密钥错误
排查步骤：
- 确认 Header 名称为
Authorization，而非X-API-Key（部分早期文档可能不同，以最新文档为准） - 检查 Key 是否包含多余空格或换行符
- 尝试在浏览器中直接访问
https://v1.apizero.cn/api/moji-weather?city=北京&api_key=YOUR_KEY排查 - 如果使用环境变量注入，确保变量已正确导出
4. 查询模式错误：op 参数与必要参数不匹配
现象：
- 请求
?op=search但缺少keyword，返回code: 400，msg: "search 模式需要 keyword 参数" - 请求
?op=history但缺少day或month，返回类似错误
排查步骤：
- 确认
op取值只能是search或history，拼写错误（如“seach”）会导致被当作实况查询，此时keyword或day参数会被忽略 - 若想只查实况，不要传
op参数或传空 - 对于历史查询，若只传
day而不传month，API 会尝试从day中提取月份；建议明确传递month参数
5. 历史日期超出范围
现象：返回code: 400，msg: "日期超出可查询范围"
原因：
- 请求的未来日期（只能查过去）
- 请求的月份过于久远（接口建议查近 40 天以内）
- 当前月只能查到昨天，今天的数据尚未产生
排查步骤：
- 确认
day格式为YYYY-MM-DD，且是过去日期 - 对于整月查询，
month格式为YYYYMM，且不超过上月（当前月只能返回 1 号至昨天） - 如果仍失败，尝试缩小日期范围
6. QPS 超出限制
现象：HTTP 429 Too Many Requests，响应体可能为空或包含错误描述
原因：短时间请求超过 5 次/秒
排查步骤：
- 检查调用逻辑，是否在循环中无间隔调用
- 添加本地限流：使用令牌桶或固定窗口，每秒最多 5 次
- 对于批量任务，适当加入
time.Sleep(200ms)或使用协程池控制并发 - 如果业务确实需要高并发，关注文档是否有更高 QPS 的申请通道（以文档为准）
7. 服务端缓存导致数据滞后
现象：查询实况天气，但数据和本地其他源差距超过 5 分钟
原因：实况数据缓存 5 分钟，历史数据缓存更久
排查步骤：
- 观察响应中的
_cached字段：true表示缓存命中 - 不应依赖实时性要求高于 5 分钟的场景
- 如果数据明显有问题（如温度与官方 App 差异巨大），可能是缓存未刷新，稍后再试
工程化注意事项
- 参数校验：在后端调用前，先检查
city或id是否为空，避免浪费网络请求 - 错误重试：对于 429 或 5xx 错误，建议指数退避重试（最多 3 次）
- 日志记录：记录每次请求的 URL（去掉 API Key）、响应
code、msg和耗时，便于排错 - 缓存友好：合理利用本地缓存，减少对 API 的重复调用，例如将实况天气缓存 3 分钟
- 时区处理：返回的
timezone为数字（如 8），所有时间戳均为 Unix 毫秒，使用时注意转换为本地时间 - 文档对齐：客户端与服务端使用同一份 API 文档，尤其关注
Authorization字段名和参数类型
参考文档
- 接口文档主页：https://apizero.cn/aidocs/moji-weather
- 原始文档（Markdown）：https://apizero.cn/aidocs/moji-weather/raw.md
