资讯 文档
技术能力
语音技术
文字识别
人脸与人体
图像技术
语言与知识
视频技术

错误码表

错误码表

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 字段)

codeSERVER_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 未知错误

错误处理示例

import { OcrError, OcrStage } from '@baidu/ocr-core';

function handleError(error: OcrError): void {
  console.error(`[OCR Error] code: ${error.code}, errorCode: ${error.errorCode}, ` +
    `message: ${error.message}, stage: ${error.stage}, logId: ${error.logId}`);

  switch (error.code) {
    case 'AUTH_ERROR':
      // 鉴权失败
      break;
    case 'NETWORK_ERROR':
      // 网络错误,提示检查网络
      break;
    case 'SERVER_ERROR':
      // 服务端业务错误,errorCode 是服务端 error_code
      console.error(`服务端错误码: ${error.errorCode}, logId: ${error.logId}`);
      break;
    case 'CAMERA_OPEN_FAILED':
      // 相机打开失败
      break;
    case 'AUTO_CAPTURE_TIMEOUT':
      // 自动采集超时
      break;
    case 'IMAGE_LOAD_FAILED':
      // 图片加载失败
      break;
    default:
      break;
  }
}

问题排查步骤

步骤 操作 说明
1 查看 error.code 确定错误大类
2 查看 error.stage 确定错误发生阶段(INIT / AUTH / CAPTURE / RECOGNIZE / PARSE
3 查看 error.errorCode 获取详细数值错误码
4 查看 error.message 获取错误描述
5 记录 error.logId 用于向百度技术支持提供追踪信息
6 检查网络和权限 排除基础环境问题
7 检查鉴权配置 确认 token/密钥有效
上一篇
FAQ
下一篇
SDK 合规使用指南