星座运势查询：调用失败排查（ret_code 与 showapi_res_code 区别）
星座运势查询错误处理ret_codeappKey错误 # 星座运势查询：调用失败排查（ret_code 与 showapi_res_code 区别）
> 接口 872（两接入点）· 免费 · 适用：已接入开发者、需做错误处理的工程师 · 阅读时间：约 6 分钟
## TL;DR
- 响应有两层状态码：**系统级 `showapi_res_code`**（鉴权/参数/频率，失败非 0）与**业务级 `ret_code`**（在 `showapi_res_body` 内，0 成功）。
- 先判 `showapi_res_code === 0` 再判 `body.ret_code === "0"`，两层都过才算成功。
- 本次实测：用错误/未授权 AppKey 调 872-1 返回 `showapi_res_code: -1004 / "appKey err"`，属系统级鉴权失败。
## Why：为什么要区分两层
很多团队只判断 HTTP 200 就认为成功，结果拿到 `showapi_res_body` 为空或业务失败。ShowAPI 的响应结构里，系统级错误（如 AppKey 错、频率超限）和业务级错误（参数组合无效）分属两个字段，必须分别判断，否则会出现「请求通了但数据为空」的诡异 bug。
## What：两层状态码
| 层级 | 字段位置 | 成功值 | 含义 |
|------|----------|--------|------|
| 系统级 | 根 `showapi_res_code` | `0` | 平台层是否受理（鉴权、频率、路由） |
| 业务级 | `showapi_res_body.ret_code` | `"0"` | 业务是否成功（参数组合是否有效） |
> 业务级 `ret_code` 文档标注「0 为成功，其他失败」（字符串）。系统级 `showapi_res_code` 常见为 0 成功、负数表示各类平台错误。
## How：健壮的错误处理
Python（requests）：
```python
import requests
def call_horoscope(params: dict):
r = requests.get("https://route.showapi.com/872-1", params=params, timeout=10)
data = r.json()
# 第一层：系统级
if data.get("showapi_res_code") != 0:
raise RuntimeError(f"系统错误 {data.get('showapi_res_code')}: {data.get('showapi_res_error')}")
body = data["showapi_res_body"]
# 第二层：业务级
if str(body.get("ret_code")) != "0":
raise RuntimeError(f"业务错误 ret_code={body.get('ret_code')}")
return body
try:
body = call_horoscope({"appKey": "YOUR_APPKEY", "star": "shizi"})
except RuntimeError as e:
# 记录日志 + 走兜底文案，不要白屏
print("运势暂不可用：", e)
```
## 实测案例（真实证据）
对 `https://route.showapi.com/872-1` 用未对 872 授权的 AppKey 请求，返回：
```json
{ "showapi_res_error": "appKey err", "showapi_res_code": -1004, "showapi_res_body": {} }
```
这属于**系统级鉴权失败**（`showapi_res_code: -1004`），应在调用前校验 AppKey 有效性，并在 UI 给出「服务暂不可用」兜底。
## 进阶 / 边界
- **系统级枚举**：具体 `showapi_res_code` 负值枚举（鉴权/参数/频率等）以平台文档为准；本文仅实测确认 `-1004 = appKey err`。不建议靠猜测补全其它码值。
- **业务级 ret_code**：文档仅给出「0 成功，其他失败」，未穷举其它值；非 0 时直接按失败处理并打日志即可。
- **超时与重试**：建议 `timeout=10`，对网络抖动做有限指数退避重试，但不要对「鉴权失败」重试（必败）。
## FAQ
**Q：HTTP 200 但没数据，是怎么回事？**
A：多半是系统级 `showapi_res_code` 非 0（如 -1004 appKey err），业务体为空。先查该字段再查 `ret_code`。
**Q：ret_code 是数字还是字符串？**
A：文档标注为字符串（"0"），判断时用 `str(body.get("ret_code")) != "0"` 最稳，避免类型陷阱。
**Q：频率限制会返回什么？**
A：通常体现为系统级 `showapi_res_code` 非 0（频率类错误）。具体码值以平台文档为准；做好[缓存](https://www.showapi.com/guides/horoscope-cache-872)可从根本上规避。
## 下一步阅读
- [免费接口也有限流：星座运势查询缓存策略](https://www.showapi.com/guides/horoscope-cache-872)
- [星座运势查询：5 分钟接入指南](https://www.showapi.com/guides/horoscope-quickstart-872)
- [星座运势查询返回字段全解](https://www.showapi.com/guides/horoscope-response-fields-872)
- **本系列共 13 篇**：查看[星座运势 API 开发指南总目录](https://www.showapi.com/guides/horoscope-guides-872)
