一、认证类错误：API Key与Secret Key配置问题

1.1 无效凭证错误（401 Unauthorized）

当出现{"error_code":110,"error_msg":"Access token invalid or no longer valid"}时，表明认证凭证失效。常见原因包括：

• 密钥未正确配置：检查access_token生成代码

  from aip import AipOcr
  APP_ID = '你的App ID'
  API_KEY = '你的Api Key'
  SECRET_KEY = '你的Secret Key'
  client = AipOcr(APP_ID, API_KEY, SECRET_KEY)

• 密钥过期：百度OCR的access_token有效期为30天，需定期刷新
• 网络中间件修改：代理服务器可能篡改认证头信息

1.2 权限不足错误（403 Forbidden）

错误码{"error_code":111,"error_msg":"Access denied"}通常由以下情况触发：

• 套餐类型不匹配：基础版账号调用高级版接口
• 调用频率超限：免费版每日500次调用限制
• IP白名单限制：未将调用方IP加入控制台的安全设置

二、请求参数类错误：数据格式与内容问题

2.1 图像参数错误（400 Bad Request）

典型错误{"error_code":112,"error_msg":"Image not exists"}的排查步骤：

1. 验证图片路径：使用绝对路径测试

   import os
   image_path = '/absolute/path/to/image.jpg'
   assert os.path.exists(image_path), "文件不存在"

2. 检查图片格式：仅支持JPG/PNG/BMP格式
3. 图片大小限制：单张图片需≤5MB，分辨率建议800×600以上

2.2 识别类型错误（400 Bad Request）

当出现{"error_code":113,"error_msg":"Unsupported recognize type"}时：

• 检查recognize_granularity参数值：仅支持big/small/auto
• 验证language_type设置：中文识别需指定CHN_ENG
• 确认probability参数：仅在特定接口可用

三、网络通信类错误：连接与超时问题

3.1 连接超时错误（504 Gateway Timeout）

处理{"error_code":120,"error_msg":"Request timeout"}的优化方案：

• 调整超时设置：

  client.setConnectionTimeoutInMillis(5000)  # 连接超时5秒
  client.setSocketTimeoutInMillis(30000)    # 响应超时30秒

• 检查代理配置：

  import os
  os.environ['HTTP_PROXY'] = 'http://proxy.example.com:8080'

• 测试网络连通性：

  curl -v "https://aip.baidubce.com/rest/2.0/ocr/v1/general_basic?access_token=YOUR_TOKEN"

3.2 SSL证书错误（SSL Error）

当出现[SSL: CERTIFICATE_VERIFY_FAILED]时：

• 更新证书库：

  pip install --upgrade certifi

• 临时禁用验证（不推荐生产环境使用）：

  import ssl
  ssl._create_default_https_context = ssl._create_unverified_context

四、服务端类错误：系统与配额问题

4.1 服务不可用错误（503 Service Unavailable）

错误码{"error_code":140,"error_msg":"Service temporarily unavailable"}的应对措施：

• 检查百度OCR服务状态页面
• 实现重试机制：
  ```python
  import time
  from aip import AipOcr

def ocr_with_retry(client, image_path, max_retries=3):
for attempt in range(max_retries):
try:
with open(image_path, ‘rb’) as f:
image = f.read()
return client.basicGeneral(image)
except Exception as e:
if attempt == max_retries - 1:
raise
time.sleep(2 ** attempt) # 指数退避

## 4.2 配额耗尽错误（429 Too Many Requests）
当出现`{"error_code":141,"error_msg":"QPS limit exceeded"}`时：
- 升级服务套餐：专业版支持50QPS
- 实现请求限流：
```python
from ratelimit import limits, sleep_and_retry
@sleep_and_retry
@limits(calls=10, period=1)  # 每秒最多10次调用
def limited_ocr_call(client, image):
    return client.basicGeneral(image)

五、最佳实践与调试工具

5.1 日志记录方案

import logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('ocr_errors.log'),
        logging.StreamHandler()
    ]
)
try:
    result = client.basicGeneral(image)
except Exception as e:
    logging.error(f"OCR调用失败: {str(e)}", exc_info=True)

5.2 官方调试工具

• 使用百度OCR控制台的「API调试」功能
• 安装官方SDK提供的诊断工具：

  pip install aip-diagnose
  aip-diagnose --api_type ocr --action test_connectivity

5.3 版本兼容性检查

确保SDK版本与API版本匹配：

from aip import AipOcr
print(f"SDK版本: {AipOcr.__version__}")  # 应≥4.16.7

六、完整调用示例

from aip import AipOcr
import time
import logging
# 配置日志
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
# 初始化客户端
APP_ID = '你的AppID'
API_KEY = '你的ApiKey'
SECRET_KEY = '你的SecretKey'
client = AipOcr(APP_ID, API_KEY, SECRET_KEY)
# 设置超时
client.setConnectionTimeoutInMillis(5000)
client.setSocketTimeoutInMillis(30000)
def recognize_text(image_path):
    try:
        # 读取图片
        with open(image_path, 'rb') as f:
            image = f.read()
        # 调用API（带重试）
        max_retries = 3
        for attempt in range(max_retries):
            try:
                result = client.basicGeneral(image)
                logger.info(f"识别成功: {result}")
                return result
            except Exception as e:
                if attempt == max_retries - 1:
                    logger.error(f"所有重试失败: {str(e)}", exc_info=True)
                    raise
                time.sleep(2 ** attempt)
    except FileNotFoundError:
        logger.error(f"图片文件不存在: {image_path}")
    except Exception as e:
        logger.error(f"未知错误: {str(e)}", exc_info=True)
if __name__ == "__main__":
    try:
        result = recognize_text("test.jpg")
        print("识别结果:", result)
    except Exception as e:
        print("处理失败:", str(e))

通过系统化的错误分类和解决方案，开发者可以快速定位并解决Python调用百度OCR API时遇到的问题。建议结合官方文档和诊断工具进行综合排查，同时注意保持SDK版本更新以获得最佳兼容性。