错误码表
错误码表
SDK 错误码(code 字段)
OcrError.code 为 SDK 内部定义的字符串错误码,标识错误大类。业务方应首先根据 code 分类处理。
参数和初始化错误
| code |
说明 |
常见原因 |
处理建议 |
INVALID_PARAMETER |
参数无效 |
OcrType 与 params 类型不匹配,必填参数缺失 |
检查传入参数的类型和值 |
INVALID_RECOGNIZE_OPTIONS |
识别参数类型不匹配 |
传入的 RecognizeParams 子类与 OcrType 不对应 |
确认参数类与识别类型匹配 |
INVALID_RESULT_TYPE |
识别结果类型不匹配 |
OcrResultCallback 泛型类型与实际结果不一致 |
使用正确的结果类型泛型 |
AUTH_ERROR |
鉴权失败 |
token 过期、密钥错误、License 不匹配 |
检查鉴权配置,详见鉴权错误码表 |
DUPLICATE_ADAPTER |
能力重复注册 |
同一 OcrType 被多次注册 |
检查是否重复引入模块 |
UNSUPPORTED_OCR_TYPE |
识别类型不支持 |
SDK 未注册该识别类型 |
确认已引入对应能力模块 |
UNSUPPORTED_ENGINE_MODE |
引擎模式不可用 |
在线/离线引擎未就绪 |
确认初始化成功且引擎可用 |
OFFLINE_MODEL_NOT_FOUND |
离线模型不存在 |
模型文件未放置或路径错误 |
检查模型文件位置 |
OFFLINE_ENGINE_NOT_AVAILABLE |
离线引擎不可用 |
离线能力模块未集成 |
确认已集成对应离线模块 |
PERMISSION_DENIED |
权限不足 |
未授予 CAMERA 或 INTERNET 权限 |
检查 module.json5 权限声明和运行时授权 |
采集阶段错误
| code |
说明 |
常见原因 |
处理建议 |
USER_CANCEL |
用户取消 |
用户主动退出采集页 |
正常流程,通过 onCanceled 回调处理 |
CAMERA_OPEN_FAILED |
相机打开失败 |
设备无相机、权限未授予、相机被占用 |
检查设备和权限状态 |
CAMERA_CAPTURE_FAILED |
相机拍摄失败 |
拍照过程异常 |
提示用户重试 |
AUTO_CAPTURE_TIMEOUT |
自动采集超时 |
长时间未检测到合格画面 |
提示用户调整角度或切换手动模式 |
IMAGE_BLUR |
图片模糊 |
图片清晰度不满足要求 |
提示用户重新拍摄 |
NO_TARGET |
未检测到目标 |
画面中未识别到证件/文字主体 |
提示用户对准目标 |
FRAME_SAMPLE_ERROR |
帧采样失败 |
自动采集过程中发生异常 |
提示用户重试或切换手动模式 |
IMAGE_LOAD_FAILED |
图片加载失败 |
PixelMap 无效、文件不存在或格式不支持 |
检查图片来源和格式 |
LAYOUT_INVALID |
布局配置无效 |
自定义布局缺少必需组件 |
检查自定义布局配置 |
网络和服务端错误
| code |
说明 |
常见原因 |
处理建议 |
NETWORK_ERROR |
网络错误 |
无网络连接、DNS 解析失败、请求超时 |
检查网络状态,确认 INTERNET 权限 |
SERVER_ERROR |
服务端业务错误 |
服务端返回 error_code 非 0 |
查看 errorCode 字段获取具体服务端错误码 |
INVALID_RESPONSE |
响应解析失败 |
服务端返回格式异常 |
检查网络中间件是否篡改响应 |
服务端错误码(errorCode 字段)
当 code 为 SERVER_ERROR 时,errorCode 字段透传服务端 error_code 原值。
通用错误
| 错误码 |
错误信息 |
说明 |
| 17 |
Open api daily request limit reached |
每天请求量超限额 |
| 18 |
Open api qps request limit reached |
QPS 超限额 |
| 19 |
Open api total request limit reached |
请求总量超限额 |
| 100 |
Invalid parameter |
无效参数 |
| 110 |
Access token invalid or no longer valid |
Access Token 过期失效,请重新获取有效的 token |
| 111 |
Access token expired |
Access Token 已过期 |
OCR 业务错误
| 错误码 |
错误信息 |
说明 |
| 216015 |
module closed |
模块关闭 |
| 216100 |
invalid param |
非法参数 |
| 216101 |
not enough param |
参数数量不够 |
| 216102 |
service not support |
业务不支持 |
| 216103 |
param too long |
参数太长 |
| 216110 |
appid not exist |
APP ID 不存在 |
| 216111 |
invalid userid |
非法用户 ID |
| 216200 |
empty image |
空的图片 |
| 216201 |
image format error |
图片格式错误 |
| 216202 |
image size error |
图片大小错误 |
| 216300 |
db error |
DB 错误 |
| 216400 |
backend error |
后端系统错误 |
| 216401 |
internal error |
内部错误 |
| 216500 |
unknown error |
未知错误 |
| 216600 |
id number format error |
身份证的 ID 格式错误 |
| 216601 |
id number and name not match |
身份证的 ID 和名字不匹配 |
| 216630 |
recognize error |
识别错误 |
| 216631 |
recognize bank card error |
识别银行卡错误(通常为检测不到银行卡) |
| 216632 |
ocr unknown error |
OCR 未知错误 |
错误处理示例
1import { OcrError, OcrStage } from '@baidu/ocr-core';
2
3function handleError(error: OcrError): void {
4 console.error(`[OCR Error] code: ${error.code}, errorCode: ${error.errorCode}, ` +
5 `message: ${error.message}, stage: ${error.stage}, logId: ${error.logId}`);
6
7 switch (error.code) {
8 case 'AUTH_ERROR':
9
10 break;
11 case 'NETWORK_ERROR':
12
13 break;
14 case 'SERVER_ERROR':
15
16 console.error(`服务端错误码: ${error.errorCode}, logId: ${error.logId}`);
17 break;
18 case 'CAMERA_OPEN_FAILED':
19
20 break;
21 case 'AUTO_CAPTURE_TIMEOUT':
22
23 break;
24 case 'IMAGE_LOAD_FAILED':
25
26 break;
27 default:
28 break;
29 }
30}
问题排查步骤
| 步骤 |
操作 |
说明 |
| 1 |
查看 error.code |
确定错误大类 |
| 2 |
查看 error.stage |
确定错误发生阶段(INIT / AUTH / CAPTURE / RECOGNIZE / PARSE) |
| 3 |
查看 error.errorCode |
获取详细数值错误码 |
| 4 |
查看 error.message |
获取错误描述 |
| 5 |
记录 error.logId |
用于向百度技术支持提供追踪信息 |
| 6 |
检查网络和权限 |
排除基础环境问题 |
| 7 |
检查鉴权配置 |
确认 token/密钥有效 |