错误与限制

Numora 对外 API 开发者预览版的 HTTP 状态码、错误响应模型、接入限制与重试建议。

范围

本页说明 Numora 对外 API 开发者预览版的错误模型与运行限制。

它同时覆盖两层信息：

外部集成应遵循的 public API 响应契约
当前 Numora 应用链路已经真实生效的上传与提取约束

HTTP 状态码

对外 API 使用标准 HTTP 状态码。

200 OK：请求成功，并返回完整响应体
202 Accepted：请求已被接收，后续会异步处理
400 Bad Request：请求格式错误，或缺少必要输入
401 Unauthorized：API key 缺失或无效
403 Forbidden：API key 有效，但没有访问该资源的权限
404 Not Found：请求的资源不存在
409 Conflict：请求与当前资源状态或幂等预期冲突
422 Unprocessable Entity：JSON 结构有效，但语义值不合法
429 Too Many Requests：客户端超过当前限流阈值
500、502、503、504：服务端或下游 provider 出现错误

错误响应结构

对外 API 错误响应应使用稳定结构：

{
  "error": {
    "code": "file_too_large",
    "message": "file size exceeds the 30 MB limit",
    "request_id": "req_01jpy7v0j8w8f1sh3j2j1j0t7v"
  }
}

request_id 也应同时出现在 x-request-id 响应头中。

常见错误码

预览版常见错误码包括：

unauthorized
forbidden
invalid_payload
invalid_schema
unsupported_file_type
file_too_large
not_found
conflict
rate_limited
insufficient_credits
provider_error
internal_error

当前接入限制

当前 Numora 应用中的上传与提取链路已经生效以下约束：

单文件最大上传体积：30 MB
支持的上传格式：PDF、JPEG/JPG、PNG、TIFF、HEIC、HEIF、WEBP、GIF、BMP
首批公开 schema：invoice_v2、receipt_v1、contract_v1
请求关联响应头：x-request-id

这些值基于当前实现，后续可能按套餐、环境或具体 endpoint 进一步细化。

重试建议

客户端应按状态类别决定重试策略：

对 429 和 5xx 响应使用指数退避加随机抖动
重试同一份业务文档创建时，复用相同的 external_id
重放同一次 delivery callback 时，才复用同一个 execution_id
不要在未修正请求内容前盲目重试 4xx
对异步文档创建，应优先轮询 GET /v1/documents/{id} 或消费 webhook，而不是反复重复提交相同文档

面向当前 Numora 实现的说明

当前内部 OCR 链路已经使用 x-request-id 进行请求关联，并在上传型流程中执行 30 MB 文件限制。

如果后续 public API 建立在同一条接入链路之上，就应继续在文档中明确这些约束，直到实现发生变更。