跳过主要内容
FreeAIOCR logoFreeAIOCR
API 文档

错误与重试

查看 FreeAIOCR API 错误码、幂等请求、正确重试方式和结算状态不明时的安全处理方法。

APIAPI 密钥API 计费

这些公共指南适用于图片转文字和图片转表格。各接口支持的输入、格式和特有错误，请查看对应接口参考。

错误响应

错误响应 JSON 示例：

{
  "request_id": "b2c8ec98-2a36-4f87-99d2-3d7839b92518",
  "error": {
    "code": "insufficient_balance",
    "message": "Recognition did not complete",
    "required_reservation_usd": "0.011288000"
  }
}

HTTP 状态码

HTTPerror.code
400invalid_request, invalid_idempotency_key, invalid_image
401unauthorized
402insufficient_balance
403account_unavailable
405invalid_request
409idempotency_conflict, request_in_progress
413image_too_large, input_limit_exceeded
415unsupported_media_type
422recognition_blocked
429rate_limit_exceeded, concurrency_limit_exceeded
502recognition_failed, output_truncated, empty_result, invalid_usage
503service_unavailable, settlement_pending, export_failed
504request_timeout
HTTP原因处理建议
400 / 413 / 415请求无效、图片过大或格式不支持修改上传内容或缩小图片
405请求方法不正确使用 POST
401缺少或无效的 API Key检查 Bearer 密钥
403账户不可用验证邮箱或解除账户限制
402可用余额不足充值并查看 error.required_reservation_usd；参见余额冻结规则
409编号冲突或请求正在处理request_in_progress 保留原编号和图片等待重试；编号冲突时纠正业务操作编号
429请求频率或并发超限按照 Retry-After 等待
422 / 已确认的 502识别失败且结果已确定本次识别不收费；先查明错误，再决定是否发起新操作
503 / 504 / 状态不明服务、结算或超时状态不确定不能假设未扣费，应使用原 Idempotency-Key 和原图片重试

错误以 JSON 返回，包含 request_id、error.code 和 error.message。所有响应均设置 Cache-Control: no-store，识别不采用流式输出；成功响应使用选择的格式，错误仍为 JSON。联系支持时请保留 X-Request-Id。

幂等性

Idempotency-Key 是调用方生成的业务操作编号，长度 16～128 个 ASCII 字母、数字或 . _ : -。新图片使用新的唯一编号，重试则保持编号、原始图片字节和 MIME 一致。编号按账户共享，更换 API 密钥也不改变操作。受理后 24 小时内，已完成操作的重试返回原 request_id、结果和费用，并带有 Idempotency-Replayed: true，不重新生成或扣费。

不同业务操作或不同接口必须使用不同的 Idempotency-Key。图片转文字与图片转表格复用编号会返回 409 idempotency_conflict。同一操作切换格式时，复用原编号和原图片。

重试策略

遇到网络错误、request_in_progress 或 settlement_pending 时，保留原编号和图片，按 Retry-After 秒数等待后重试；结算不明确时不要另建操作。已保存的终态失败会重放相同错误，确认失败后确需重新识别才换新编号。24 小时后同编号可能创建新的计费操作；尚未恢复的请求仍不能复用编号。

计费安全

已确认的识别失败不收费，但响应丢失或 settlement_pending 可能意味着已结算，或冻结金额尚未释放。结算结果不明时不得使用新 Idempotency-Key 发起另一笔操作；保留原编号与原图片重试，联系支持时提供 X-Request-Id。