条码生成与识别：ret_code 非 0 与识别失败排查指南
# 条码生成与识别：ret_code 非 0 与识别失败排查指南
> 接口/接入点：条码生成与识别（apiCode 1129）· 1129-1/2/3/4 ｜ 是否免费：免费 ｜ 请求方式：POST/GET ｜ 返回格式：JSON ｜ 适用人群：开发者、运维 ｜ 阅读时间：约 6 分钟
## TL;DR
- 文档只定义 `ret_code`：**"0" 成功，其他值失败**。未枚举任何具体错误码数字，请勿编造 -1/-2 等。
- 判断成败一律用 `ret_code != "0"` → 失败，做统一兜底（重试/降级/人工）。
- 常见失败多来自三类：图片质量问题、传参不匹配、网络/服务侧异常。
## Why：为什么错误码必须"诚实处理"
很多接口会给出细粒度错误码（-1 参数错、-2 超限…），但本接口的官方文档**只给了 0/其他 二态**，没有具体码表。若文章或代码里硬编一套"错误码含义"，就是无依据的编造，会误导排查。正确做法是把非 0 当成"需要关注的具体失败"，结合请求上下文去定位。
## What：可依赖的失败信号
| 信号 | 含义 | 处理 |
|----|----|----|
| `body.ret_code == "0"` | 业务成功 | 取 `imgUrl`/`retText` |
| `body.ret_code != "0"` | 业务失败（具体原因未文档化） | 进入兜底流程 |
| `showapi_res_code` 非 0 | 系统级异常（网关/鉴权） | 检查 appKey、网络、档位 |
| 响应超时/网络错误 | 未到达业务层 | 指数退避重试 |
## How：健壮调用模板（Python）
```python
import requests, time
APPKEY = "YOUR_APPKEY"
URL = f"https://route.showapi.com/1129-3?appKey={APPKEY}"
def recognize(img_url: str, max_retry: int = 2):
for attempt in range(max_retry + 1):
try:
r = requests.post(URL, data={"imgUrl": img_url}, timeout=10).json()
except requests.RequestException as e:
# 网络层异常：指数退避
if attempt < max_retry:
time.sleep(2 ** attempt); continue
return None, f"网络异常: {e}"
body = r.get("showapi_res_body", {})
if body.get("ret_code") == "0":
return body.get("retText"), None
# 业务失败：非 0，记录后重试一次
if attempt < max_retry:
time.sleep(1); continue
return None, f"ret_code={body.get('ret_code')} res_err={r.get('showapi_res_error')}"
return None, "未知失败"
text, err = recognize("https://your-cdn.com/box.png")
if err:
print("识别失败:", err, "→ 转人工/重新采集")
else:
print("识别成功:", text)
```
cURL：
```bash
curl -s -X POST "https://route.showapi.com/1129-3?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "imgUrl=https%3A%2F%2Fyour-cdn.com%2Fbox.png"
```
Node.js：
```javascript
const APPKEY = "YOUR_APPKEY";
const body = new URLSearchParams({ imgUrl: "https://your-cdn.com/box.png" });
const res = await fetch(`https://route.showapi.com/1129-3?appKey=${APPKEY}`, {
method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }, body
});
const rb = (await res.json()).showapi_res_body;
if (rb.ret_code !== "0") throw new Error("识别失败 ret_code=" + rb.ret_code);
console.log(rb.retText);
```
## 返回示例与解析
失败示例（结构示意，具体 ret_code 值以实际返回为准）：
```json
{ "showapi_res_code": 0, "showapi_res_body": { "retText": "", "ret_code": "非0值" } }
```
## 进阶 / 边界
- **不要猜错误码**：文档未给具体码表，代码里不要写 `if ret_code == "-2": ...` 这类分支；统一 `!= "0"` 失败即可。
- **高频失败先查图片**：识别失败绝大多数源于图模糊、条码倾斜/截断、光照反光。先优化采集端，再谈重试。
- **生成失败查 content/formatType**：内容与该格式编码规则不匹配会导致失败，见 [13 种格式对照](https://www.showapi.com/guides/barcode-format-types-1129)。
- **档位限制**：免费接口有使用档次限制，超限可能表现为调用失败，详见 [档位说明](https://www.showapi.com/free-api)。
## FAQ
**Q：ret_code 非 0 时有没有错误说明字段？**
系统级错误可见 `showapi_res_error`（字符串），业务级 `ret_code` 文档仅定义为"非 0 即失败"，未给出逐码含义。排查时优先结合请求参数与图片质量定位。
**Q：识别一直返回空 retText 但 ret_code=0 算成功吗？**
`ret_code=0` 表示接口调用成功，但 `retText` 为空通常意味着图中未识别出条码；建议换清晰图重试，业务上按"未识别"处置而非"成功"。
**Q：怎么区分"图不行"还是"接口挂了"？**
看 `showapi_res_code` 与网络层：能拿到正常 JSON 但 `body.ret_code` 非 0，多为图/参数问题；网络超时或 `showapi_res_code` 异常，多为服务/网络/鉴权问题。
**Q：重试会不会被限流？**
免费接口有档位限制，盲目高频重试可能触限制；建议指数退避 + 有限次数（如 2 次）重试。
## 相关能力 / 下一步阅读
- [条码生成与识别：返回字段全解（imgUrl / retText / ret_code / msg）](https://www.showapi.com/guides/barcode-response-fields-1129)
- [条码识别三种传图方式怎么选：上传图片 / 图片链接 / Base64 实战对比](https://www.showapi.com/guides/barcode-three-input-modes-1129)
- [条码生成与识别：13 种条码格式（formatType）对照与选型指南](https://www.showapi.com/guides/barcode-format-types-1129)
- **本系列共 12 篇**：查看[条码生成与识别指南总目录](https://www.showapi.com/guides/barcode-guides-1129)
