印刷体OCR识别错误码排查：10 参数错误到 90 识别异常逐条对照
# 印刷体OCR识别错误码排查：10 参数错误到 90 识别异常逐条对照
> 接口 926（接入点 926-1） · 免费 · POST/GET · JSON · 适用人群：已接入、遇到报错的开发者 · 阅读时间：约 6 分钟
## 核心要点
- 业务成败只看 `showapi_res_body.ret_code`：`0` 成功，`10~90` 是 10 档错误，每档含义固定。
- 多数错误可在客户端前置规避：参数校验、`img_base64`/`img_url` 二选一、图片压缩、URL 可达性。
- `80/90`（超时/异常）可退避重试；`50/60/20`（过大/解析/格式）重试无效，需先修图。
## Why：错误码不是天书
接入后遇到 `ret_code=50` 一脸懵？其实每一档都对应明确的触发原因和修复动作。把这张表存好，线上出问题直接对照处理，少查半天文档。
## What：ret_code 总表
| ret_code | 含义 | 触发原因 |
|----------|------|---------|
| 0 | 识别成功 | — |
| 10 | 参数错误 | 未传 `img_url`/`img_base64`，或参数格式不对 |
| 20 | 文件格式错误 | 非 JPEG/PNG，或图片损坏 |
| 30 | 操作失败，请勿重复提交 | 短时间内重复提交同一请求 |
| 40 | 文件下载失败 | `img_url` 不可访问 / 超时 / 防盗链 |
| 50 | 文件内容过大 | 超过 base64 0.7M / URL 1M 上限 |
| 60 | 图片解析失败 | 像素过大或解码异常（建议 < 1200×1200） |
| 70 | OCR 识别失败 | 图片无文字 / 文字极不清晰 |
| 80 | 服务超时 | 图片过大、并发过高，建议降级重试 |
| 90 | 识别异常 | 服务端异常，稍后重试 |
`remark` 字段会携带更具体的错误信息，排查时务必打印它。
## How：统一错误处理（Python）
```python
import requests
def ocr(img_payload: dict) -> dict:
url = "https://route.showapi.com/926-1"
params = {"appKey": "YOUR_APPKEY"}
r = requests.post(url, params=params, data=img_payload, timeout=10)
rb = r.json()["showapi_res_body"]
code = rb["ret_code"]
if code == 0:
return {"ok": True, "data": rb.get("list") or rb.get("str")}
# 可重试类
if code in (80, 90):
return {"ok": False, "retry": True, "ret_code": code, "msg": rb.get("remark")}
# 不可重试类（先修图/改参数）
return {"ok": False, "retry": False, "ret_code": code, "msg": rb.get("remark")}
# 调用示例
result = ocr({"img_url": "https://your-cdn.example.com/a.png", "need_all_region": "1"})
print(result)
```
**Node.js（fetch）**
```javascript
async function ocr(payload) {
const res = await fetch("https://route.showapi.com/926-1?appKey=YOUR_APPKEY", {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: new URLSearchParams(payload),
});
const rb = (await res.json()).showapi_res_body;
const retryable = [80, 90].includes(rb.ret_code);
return { ok: rb.ret_code === 0, retry: retryable, code: rb.ret_code, msg: rb.remark };
}
```
**cURL（看 ret_code）**
```bash
curl -s -X POST "https://route.showapi.com/926-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "img_url=http%3A%2F%2Fshowapi-pub-hangzhou.oss-cn-hangzhou.aliyuncs.com%2Fhuangye%2Fimg_2d05ae9b-0823-4cde-9f21-79bf89e6b87d.png&need_all_region=1" \
| python -c "import sys,json;print(json.load(sys.stdin)['showapi_res_body']['ret_code'])"
```
## 逐条排查动作速查表
| ret_code | 先查什么 | 修复动作 |
|----------|---------|---------|
| 10 | 是否漏传图片参数 | 确认 `img_base64` 或 `img_url` 二选一已传 |
| 20 | 图片后缀/内容 | 转成标准 JPEG/PNG，确认未损坏 |
| 30 | 是否重复提交 | 加去重/幂等，避免同请求连发 |
| 40 | URL 是否公网可达 | 用浏览器/服务器直接访问该 URL 验证；私有资源改 `img_base64` |
| 50 | 图片大小 | base64 ≤ 0.7M、URL ≤ 1M，先压缩 |
| 60 | 分辨率/解码 | 缩放到 < 1200×1200，重导出 |
| 70 | 图中是否有字 | 换清晰样本；纯图无文字会 70 |
| 80 | 是否并发过高 | 降并发（≤8）、退避重试、缩小图片 |
| 90 | 偶发异常 | 退避重试 1~2 次，仍失败记录人工 |
## 进阶 / 边界
- **先判 ret_code 再取值**：`showapi_res_code=0`（系统级）≠ 业务成功，必须看 `ret_code`。
- **区分可重试/不可重试**：`80/90` 退避重试；`50/60/20/70` 重试无效，先修图或换样本。
- **30 别硬重试**：重复提交类，应做请求去重，而不是无脑重试。
## FAQ
**Q1：返回 0 但内容是空字符串？**
A1：若图中确实无文字可能 `70`；若 `ret_code=0` 却空，检查你是否取对了 `list`/`str`（取决于 `need_all_region`）。
**Q2：40 文件下载失败，但浏览器能打开图片？**
A2：很可能是接口服务端所在网络访问不到该 URL（防盗链、私有桶、地域限制）；改用 `img_base64` 传入。
**Q3：80 超时频繁怎么根治？**
A3：降并发（建议 ≤8）、缩小图片、对 80 做指数退避；仍频繁则考虑错峰+异步队列。
**Q4：remark 是空的说明什么？**
A4：部分错误 remark 可能为空，以 `ret_code` 为主判断；可附 `showapi_res_id` 向官方排查。
## 相关能力 / 下一步阅读
- [印刷体OCR识别返回字段全解：ret_code 与识别结果一文读懂](https://www.showapi.com/guides/printed-ocr-response-codes-926)
- [免费接口也限流：印刷体OCR识别的 10 并发与档位优化指南](https://www.showapi.com/guides/printed-ocr-limit-cost-926)
- [印刷体OCR识别：img_base64 与 img_url 两种入参怎么选？](https://www.showapi.com/guides/printed-ocr-base64-vs-url-926)
- **本系列共 12 篇**：查看[印刷体OCR识别指南总目录](https://www.showapi.com/guides/printed-ocr-guides-926)
