适用场景当你的应用需要获取全国 3 万 城市的实时天气、未来 7 天预报、24 小时逐小时趋势、空气质量指数AQI、9 项生活指数穿衣、防晒、限行等以及气象预警与农历信息时墨迹天气 API 是一个一站式的选择。它支持按城市名或内部 ID 查询也提供历史天气追溯功能。然而在实际接入过程中由于参数拼写错误、查询模式混用、鉴权配置不当等原因开发者可能会遇到各种返回错误。本文将从实战角度出发系统梳理这些常见问题及其排查方法。接口能力边界在开始排错前你需要理解该接口的核心规则请求方法GET基准地址https://v1.apizero.cn/api/moji-weatherQPS 限制5 次/秒超出后返回 429 状态码缓存策略实况数据缓存 5 分钟当月历史缓存 30 分钟过去月份历史缓存 24 小时数据用途由墨迹天气官方提供不能用于农业、保险、航运、防灾等专业决策场景所有返回数据均以 JSON 格式包裹在code/msg/data结构中。code: 0表示成功非零值表示错误。参数与鉴权请求支持两种鉴权方式二选一无需同时使用Header 方式添加Authorization: YOUR_API_KEYQuery 方式添加?api_keyYOUR_API_KEY建议使用 Header更规范核心 Query 参数参数类型必填说明citystring否城市中文名支持模糊匹配与id二选一idnumber否城市 internal_id优先精确匹配opstring否取值search/history缺省为实况keywordstring配合opsearch城市关键字支持中文、拼音、首字母limitnumber配合opsearch返回条数1~50默认 20daystring配合ophistory日期格式 YYYY-MM-DD / MM-DD / DD需额外提供monthmonthstring配合ophistory月份 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?id33搜索城市列表获取 idcurl -sS \ -X GET \ -H Authorization: YOUR_API_KEY \ https://v1.apizero.cn/api/moji-weather?opsearchkeyword大化limit5查询历史天气curl -sS \ -X GET \ -H Authorization: YOUR_API_KEY \ https://v1.apizero.cn/api/moji-weather?ophistorycity北京day2026-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: 400msg: 参数错误city 与 id 必填其一示意原因请求未提供city也未提供id或同时提供了两者但值不一致。排查步骤检查请求 URL 中是否包含?cityxxx或?idxxx确认城市名无编码问题如空格被编码为%20仍可接受但优先使用正确中文如果同时使用city和idAPI 会优先使用id但建议只传一个以避免混淆2. 无效的 internal_id现象返回code: 404msg: 未找到该城市且data为空原因传入的id在数据库中不存在可能从旧版本或第三方复制而来。排查步骤先用opsearchkeyword城市名获取正确的id注意id是 number 类型不要用字符串 33 导致类型不匹配但 API 通常会自动转换推荐仍传 numberid是内部整数不同环境可能不同请以当前接口搜索为准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_keyYOUR_KEY排查如果使用环境变量注入确保变量已正确导出4. 查询模式错误op 参数与必要参数不匹配现象请求?opsearch但缺少keyword返回code: 400msg: search 模式需要 keyword 参数请求?ophistory但缺少day或month返回类似错误排查步骤确认op取值只能是search或history拼写错误如“seach”会导致被当作实况查询此时keyword或day参数会被忽略若想只查实况不要传op参数或传空对于历史查询若只传day而不传monthAPI 会尝试从day中提取月份建议明确传递month参数5. 历史日期超出范围现象返回code: 400msg: 日期超出可查询范围原因请求的未来日期只能查过去请求的月份过于久远接口建议查近 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原始文档Markdownhttps://apizero.cn/aidocs/moji-weather/raw.md