黄历运势错误码与 ret_code 排查：日期格式/范围边界
# 黄历运势错误码与 ret_code 排查：日期格式/范围边界
> 接口 黄历运势（apiCode=856） · 免费服务 · 适用人群：已接入、排查调用失败的开发者 · 阅读时间约 6 分钟
## TL;DR
- 判断成功只看 `showapi_res_body.ret_code == 0`；非 0 即失败，且**不扣除**调用次数。
- 文档对 `ret_code` 的口径是「0 为成功，其余为失败」，**未在页面枚举具体非零错误码**；失败时以 `msg` 字段为准。
- 本接口最高频的失败原因是 `ymd` 格式不对、或日期超出 1901-01-01 至当前年份的范围。
## Why：为什么需要这篇避坑文
黄历运势的失败几乎都集中在「日期」上：格式写错、传了农历、查了不支持的年份。本文把可确定的失败边界和排查路径讲清，避免你反复猜错误码。
## What：两层返回码
黄历运势的返回分两级，排查时先分清楚看哪一级：
| 层级 | 字段 | 含义 |
|------|------|------|
| 系统级 | `showapi_res_code` | ShowAPI 平台级返回码（鉴权、参数校验等） |
| 业务级 | `showapi_res_body.ret_code` | 业务结果：0 成功；非 0 失败，不扣次数 |
> 文档对业务级 `ret_code` 的说明原文为：「0 为成功，扣除次数；其余为失败，不扣除次数」。页面**未枚举**具体非零取值，因此失败时以 `msg` 文本为准，不要对特定数字做硬编码判断。
## How：健壮的错误处理
**Python（requests）**
```python
import requests
def query_huangli(ymd):
url = "https://route.showapi.com/856-2"
params = {"appKey": "YOUR_APPKEY", "ymd": ymd}
try:
resp = requests.get(url, params=params, timeout=10)
resp.raise_for_status()
except requests.RequestException as e:
print("网络/HTTP 异常：", e)
return None
data = resp.json()
if data.get("showapi_res_code") != 0:
print("系统级失败：", data.get("showapi_res_error"))
return None
body = data.get("showapi_res_body", {})
if body.get("ret_code") != 0:
print("业务失败：", body.get("msg")) # 以 msg 为准
return None
return body
```
**cURL + jq 思路**
```bash
curl -s "https://route.showapi.com/856-2?appKey=YOUR_APPKEY&ymd=20260211" \
| python -c "import sys,json; d=json.load(sys.stdin); b=d['showapi_res_body']; print(b if b.get('ret_code')==0 else b.get('msg'))"
```
**Node.js（fetch）**
```js
const url = "https://route.showapi.com/856-2?appKey=YOUR_APPKEY&ymd=20260211";
const data = await (await fetch(url)).json();
if (data.showapi_res_code !== 0) { console.log("系统级失败：", data.showapi_res_error); }
else if (data.showapi_res_body.ret_code !== 0) { console.log("业务失败：", data.showapi_res_body.msg); }
else { console.log("成功：", data.showapi_res_body.nongli); }
```
## 已知失败边界（来自文档）
| 失败原因 | 说明 | 排查 |
|----------|------|------|
| `ymd` 缺失 / 非必填 | `ymd` 为必填，未传会失败 | 确认请求带了 `ymd` |
| `ymd` 格式错误 | 必须 `yyyyMMdd`（如 `20260211`），不接受 `2026-02-11`、`2026/2/11`、农历 | 统一用 8 位公历数字 |
| 日期超出范围 | 仅支持 1901-01-01 至**当前年份** | 早于 1901 或晚于今年会失败 |
| AppKey 错误 / 缺失 | 系统级 `showapi_res_code` 非 0 | 检查 `appKey` 是否正确、是否 urlencode |
## 进阶 / 边界
- **不要硬编码非零错误码**：因页面未枚举具体 ret_code 取值，代码中用「`ret_code != 0` → 读 `msg`」的通用分支，比匹配特定数字更稳。
- **`ymd` 用程序生成**：不要让用户手填，由你的程序取当天/所选公历日期格式化为 `yyyyMMdd` 再传入，从根上避免格式错误。
- **失败不扣次数**：失败调用不影响配额，可放心做重试/预检，但仍建议做好缓存减少无效请求（见 [缓存策略](https://www.showapi.com/guides/huangli-cache-cost-856)）。
## FAQ
**Q1：ret_code 非 0 时有没有错误码对照表？**
A：本接口文档未枚举具体非零 ret_code 取值，失败时统一以 `msg` 文本判断原因，不建议对特定数字做硬编码。
**Q2：传 2026-02-11（带横杠）为什么失败？**
A：`ymd` 格式固定为 `yyyyMMdd` 连续 8 位（如 `20260211`），不接受分隔符。
**Q3：想查明年怎么办？**
A：当前接口仅支持到当前年份；晚于今年的日期不在范围内会失败。需等年份进入支持范围后查询。
**Q4：系统级 showapi_res_code 和业务 ret_code 都要判断吗？**
A：建议都判断。系统级异常（鉴权、参数）先拦，再判断业务 ret_code，二者失败原因不同。
## 相关能力 / 下一步阅读
- [5 分钟接入黄历运势：从注册到第一条黄历数据](https://www.showapi.com/guides/huangli-quickstart-856) —— 重新核对调用姿势。
- [黄历运势返回字段全解：黄历/吉神凶煞/吉时字段一文读懂](https://www.showapi.com/guides/huangli-response-fields-856) —— 字段含义对照。
- [免费接口如何做缓存：黄历运势按日期缓存省调用次数](https://www.showapi.com/guides/huangli-cache-cost-856) —— 减少无效调用。
- **本系列共 11 篇**：查看[黄历运势指南总目录](https://www.showapi.com/guides/huangli-guides-856)
