二维码生成和识别：错误码与失败排查（ret_code 判据与 flag 拼写陷阱）
# 二维码生成和识别：错误码与失败排查（ret_code 判据与 flag 拼写陷阱）
> 接口/接入点：二维码生成和识别（apiCode=887，覆盖 887-1~887-4）· 是否免费：是 · 返回格式：JSON · 适用人群：中高级开发者、已接入排障 · 阅读时间：约 5 分钟
## 核心要点
- **成功判据统一用 `ret_code == "0"`**，最可靠，不依赖 `flag`。
- `flag` 字段存在文档拼写不一致：生成接入点（887-1）示例值为 `ture`，识别接入点（887-2/887-3）为 `true`；887-4 根本没有 `flag`。
- 识别失败表现为 `ret_code != "0"` 或 `retText` 为空。
## Why：为什么这是最容易踩的坑
新手常写 `if response.flag == true` 判断是否成功，结果生成接口返回 `ture`（字符串且拼写异常）直接误判失败；或识别 887-4 时取 `flag` 取到 `undefined`。本文把坑一次讲清。
## What：判据事实对照
| 接入点 | 成功判据 | flag 实际情况 |
|--------|---------|--------------|
| 887-1 生成 | `ret_code == "0"` | 示例值 `ture`（疑似拼写） |
| 887-2 识别(上传) | `ret_code == "0"` | 示例值 `true` |
| 887-3 识别(地址) | `ret_code == "0"` | 示例值 `true` |
| 887-4 识别(Base64) | `ret_code == "0"` | **无 flag 字段** |
> 结论：**所有接入点都应以 `ret_code == "0"` 判成功**，`flag` 仅作辅助参考，且不要做布尔/字面等值判断。
## How：稳健的判错写法
```python
import requests
def call(api, data):
resp = requests.post(f"https://route.showapi.com/{api}",
params={"appKey": "YOUR_APPKEY"}, data=data, timeout=10)
return resp.json()["showapi_res_body"]
def safe_get_text(api, data):
body = call(api, data)
if body.get("ret_code") != "0": # 唯一可靠判据
print("业务失败:", body.get("msg") or body.get("retText"))
return None
return body.get("retText") or body.get("imgUrl")
# 识别（887-4 取 retText，无 flag/msg，不会报错）
print(safe_get_text("887-4", {"imgData": "<base64>"}))
# 生成（887-1 取 imgUrl）
print(safe_get_text("887-1", {"content": "https://a.com"}))
```
```bash
# 排查时先看 ret_code
curl -s "https://route.showapi.com/887-1?appKey=YOUR_APPKEY" \
-d "content=https://a.com" \
| python -c "import sys,json;b=json.load(sys.stdin)['showapi_res_body'];print('ret_code=',b['ret_code'],'flag=',b.get('flag'))"
```
## 常见失败场景排查
| 现象 | 可能原因 | 处理 |
|------|---------|------|
| `ret_code != "0"` | 参数错误/鉴权失败/超限 | 查 `msg`/`retText`，核对 appKey 与参数 |
| 识别 `retText` 为空 | 图片无二维码/模糊/超限 | 换清晰图、检查大小（887-2 ≤100KB） |
| 生成图 404 | 超过 12h 被清理 | 参见[保存策略](https://www.showapi.com/guides/qrcode-save-strategy-887) |
| 887-4 取不到 flag | 该接入点本无 flag | 改用 ret_code 判据 |
| flag 写成 `ture` 以为失败 | 文档拼写 | 忽略 flag，看 ret_code |
## 进阶 / 边界
- **系统级 vs 业务级**：外层 `showapi_res_code` 是网关状态，`ret_code` 是业务状态；业务成功看 `ret_code`。
- **appKey 泄露/失效**：鉴权失败会在系统级返回，检查 AppKey 控制台状态。
- **档位限制**：超限可能表现为业务失败，需看[官方档位说明](https://www.showapi.com/free-api)。
## FAQ
**Q1：为什么生成接口 flag 是 "ture"？**
A：文档返回示例确为 `ture`（疑似拼写错误），并非失败。成功以 `ret_code == "0"` 判断。
**Q2：887-4 没有 flag 和 msg 正常吗？**
A：正常，是其文档定义的返回结构，只用 `ret_code` + `retText`。
**Q3：ret_code 非 0 时怎么看原因？**
A：看 `msg`（887-1/2/3）或 `retText`（887-4），仍有疑问查调用帮助。
**Q4：网络超时算成功吗？**
A：不算。需捕获超时异常并重试，不要仅凭本地异常判断业务结果。
## 相关能力 / 下一步阅读
- [二维码生成和识别：返回字段全解（ret_code / flag / imgUrl / retText）](https://www.showapi.com/guides/qrcode-response-fields-887)
- [二维码生成和识别：三种识别方式怎么选（上传 / 图片地址 / Base64）](https://www.showapi.com/guides/qrcode-recognition-compare-887)
- [二维码生成和识别：10 个实战避坑清单（100KB 上限 / 12h 清理 / 格式）](https://www.showapi.com/guides/qrcode-best-practices-887)
- **本系列共 12 篇**：查看[二维码生成和识别指南总目录](https://www.showapi.com/guides/qrcode-guides-887)
