笑话大全调用失败排查：showapi_res_code 与 ret_code 非 0 怎么办
# 笑话大全调用失败排查：showapi_res_code 与 ret_code 非 0 怎么办
> 接口 341-5 · 免费 · JSON · 适用人群：已接入用户、运维 · 阅读时间：约 5 分钟
## 核心要点
- 两层状态要分清：系统级 `showapi_res_code`（网关/鉴权）与业务级 `showapi_res_body.ret_code`（执行结果）。
- 典型失败多为 AppKey 问题或触发使用档位限制；先看 `remark` 描述再定位。
- 超时建议 20s；超时会抛网络异常而非返回业务错误。
## Why
调用偶尔失败很正常，但新手常卡在"到底哪层出错了"。笑话大全的返回有系统级和业务级两层状态，混淆它们会让你在错误的地方找原因。本篇给你一张排查路径图：先判是网关/鉴权问题，还是业务执行问题，再对症处理。
## What
| 层级 | 字段 | 含义 |
|------|------|------|
| 系统级 | `showapi_res_code` | 网关整体状态码，0 一般表示网关正常 |
| 系统级 | `showapi_res_error` | 网关错误信息 |
| 业务级 | `showapi_res_body.ret_code` | `0`=成功，其他=失败 |
| 业务级 | `showapi_res_body.remark` | 返回描述，失败时给出原因 |
## How
### 排查步骤
1. **请求是否送达？** 网络异常（超时/连接失败）会抛异常，不是返回业务错误。确认能连通 `route.showapi.com`，超时设 20s。
2. **系统级是否正常？** 看 `showapi_res_code` 与 `showapi_res_error`；非 0 多为鉴权/网关问题。
3. **业务级是否成功？** 看 `showapi_res_body.ret_code`；非 0 时读 `remark` 描述。
```python
import requests
APP_KEY = "YOUR_APPKEY"
try:
resp = requests.post(
"https://route.showapi.com/341-5",
params={"appKey": APP_KEY},
headers={"content-type": "application/x-www-form-urlencoded"},
timeout=20,
)
data = resp.json()
if data.get("showapi_res_code") != 0:
print("网关错误：", data.get("showapi_res_error"))
else:
body = data["showapi_res_body"]
if body.get("ret_code") == 0:
print(body["text"])
else:
print("业务失败：", body.get("remark"))
except requests.exceptions.Timeout:
print("请求超时（>20s），检查网络或重试")
except requests.exceptions.RequestException as e:
print("网络异常：", e)
```
## 返回示例与解析
字段结构与[返回字段全解](https://www.showapi.com/guides/joke-api-response-fields-341)一致；失败时重点看 `remark` 文本。
## 进阶 / 边界
- **本接口无错误码枚举**：文档/OpenAPI 未给出 `ret_code` 的非零枚举值，遇到非 0 以 `remark` 描述为准，不要臆造错误码含义。
- **AppKey 相关问题**：AppKey 无效/未配置会体现在系统级；确认从[控制台](https://www.showapi.com/console#/myApp)复制正确、未过期。
- **档位限制**：高频调用可能触发使用档次限制（见[缓存与档位](https://www.showapi.com/guides/joke-api-cache-tier-341)），具体以官方说明为准。
- **超时设置**：未设或过小会导致频繁超时，建议 20s。
## FAQ
**Q1：showapi_res_code 和 ret_code 该看哪个？**
两个都看：先确认 `showapi_res_code` 网关正常，再看 `ret_code` 业务是否成功；最终成败以 `ret_code == 0` 为准。
**Q2：remark 给了原因但还是不懂怎么办？**
把 `showapi_res_id`（请求唯一标识）和 `remark` 一起提交工单，便于官方定位。
**Q3：总是超时？**
确认网络可达、超时设为 20s；若持续超时可能是网络环境限制，排查出口网络。
**Q4：返回非 0 是不是接口挂了？**
不一定。多为 AppKey 或档位问题；看 `remark`、查档位说明再判断。
**Q5：档位限制有具体数字吗？**
文档未给出具体数值，以[免费 API 说明](https://www.showapi.com/free-api)为准，不臆造。
## 相关能力 / 下一步阅读
- [笑话大全返回字段全解：showapi_res_body 与 id/title/text 一文读懂](https://www.showapi.com/guides/joke-api-response-fields-341)
- [免费接口也要讲边界：笑话大全缓存策略与档位限制应对](https://www.showapi.com/guides/joke-api-cache-tier-341)
- [笑话大全：5 分钟接入，从注册到拿到第一条笑话](https://www.showapi.com/guides/joke-api-quickstart-341)
- **本系列共 10 篇**：查看[笑话大全 API 指南总目录](https://www.showapi.com/guides/joke-api-guides-341)
