Skip to content

Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.

refactor(api): simplify public error response contract

myhloli17caae651263
diff --git a/docs/next/api/README.md b/docs/next/api/README.md
index 259c2a9d..0c8e4584 100644
--- a/docs/next/api/README.md
+++ b/docs/next/api/README.md
@@ -76,7 +76,7 @@ Local Parse Server 默认监听 loopback 且不启用鉴权。启用 `--api-key`
## 通用约定
- 成功响应直接返回资源对象,没有外层 envelope。
-- 错误响应使用 OpenAI-compatible envelope,详见 [响应与错误](responses.md)。
+- 错误响应使用统一结构:必填 `code/message`,可选 `param`,详见 [响应与错误](responses.md)。
- 资源级接口及 `POST /v1/tasks` 使用 JSON,上传字节使用返回链接要求的内容类型。
- 时间字段按 endpoint 语义选择 ISO-8601 UTC 字符串或 Unix 秒级时间戳。
- 请求追踪属于部署扩展;当前 Python API Server 和 Router 不统一提供 `X-Request-Id`,详见 [请求追踪](responses.md#请求追踪)。
diff --git a/docs/next/api/file-parse.md b/docs/next/api/file-parse.md
index 5edc114b..e4d38590 100644
--- a/docs/next/api/file-parse.md
+++ b/docs/next/api/file-parse.md
@@ -198,7 +198,7 @@ X-Task-ID: job_0123456789abcdef01234567
## 错误响应
-file_parse 使用自己的错误结构,不能按主 Tasks 接口的 `ErrorDetail` 要求 `type/param` 必带。
+file_parse 使用自己的 `code/message/upstream_status` 错误结构;主 Tasks 接口的 `ErrorDetail` 为必填 `code/message` 和可选 `param`,不包含 `type`。
包装层直接返回的 `error` 包含以下三个字段,JSON 值中的 `upstream_status` 不省略:
| 字段 | JSON 类型 | 可为 null | 含义 |
@@ -251,7 +251,7 @@ Content-Type: application/json
当前错误响应不保证附加 `X-Request-ID/X-Task-ID` 或 `Location`,恢复信息从 JSON 正文读取。只取得了客户端预先指定的 ID、但没有对应恢复记录时,仍使用前一种仅含 `error` 的结构。
-状态查询成功响应中的 `error` 是持久化的错误快照:它可能是上述三字段结构并额外含 `http_status`,也可能保留上游逐文件错误的 `type/code/message/param` 或其他字段。
+状态查询成功响应中的 `error` 是持久化的错误快照:它可能是上述三字段结构并额外含 `http_status`,也可能保留上游逐文件错误的 `code/message` 和可选 `param`。历史恢复记录保持原样,可能仍含旧的 `type` 或其他字段;这不代表新 Tasks 协议接受旧字段。
其中 `http_status` 是包装层保存的错误响应状态,不是 `upstream_status`;客户端应容忍错误对象的扩展字段。
例如创建结果未知后,状态查询仍可返回 `200 OK` 和以下完整状态,不自动再次创建任务:
diff --git a/docs/next/api/files.md b/docs/next/api/files.md
index 7a76e3f3..57faf1c1 100644
--- a/docs/next/api/files.md
+++ b/docs/next/api/files.md
@@ -76,7 +76,7 @@ JSON 字段使用 `file_name`;HTTP 附件头的标准参数仍是 `filename`
## 错误与保留期
-请求失败使用非 2xx 状态码和 JSON 错误对象,其字段为 `error.type/code/message/param`,详见 [响应与错误](responses.md)。
+请求失败使用非 2xx 状态码和 JSON 错误对象,`error.code/message` 必带,`error.param` 可选,不包含 `type`,详见 [响应与错误](responses.md)。
常见情况为 `401 invalid_api_key`、`404 file_not_found`;尝试通过 `/content` 下载源文件返回 `403 feature_requires_api_key`,源文件下载不属于公共能力。
源文件通过 Tasks 的 JSON 清单和返回的上传链接创建。相同 hash 的有效缓存免传;不同文件名可以共享一份源字节,文件名和解析参数仍属于各自任务。
diff --git a/docs/next/api/health-models.md b/docs/next/api/health-models.md
index 1c2bb9de..ba76cd3f 100644
--- a/docs/next/api/health-models.md
+++ b/docs/next/api/health-models.md
@@ -44,7 +44,7 @@ GET /v1/health HTTP/1.1
| HTTP | code | 场景 |
|------|------|------|
-| 503 | `engine_error` 类模型预加载错误码 | 模型预加载未成功,服务尚不能处理请求。本地实现返回 `model_preload_dependency_missing`、`model_preload_files_missing`、`model_preload_device_unavailable` 或 `model_preload_failed`,`type` 固定为 `engine_error`。 |
+| 503 | 模型预加载错误码 | 模型预加载未成功,服务尚不能处理请求。本地实现返回 `model_preload_dependency_missing`、`model_preload_files_missing`、`model_preload_device_unavailable` 或 `model_preload_failed`,使用统一的 `error.code/message` 结构。 |
## GET `/v1/models`
diff --git a/docs/next/api/responses.md b/docs/next/api/responses.md
index 2e66faac..469913d8 100644
--- a/docs/next/api/responses.md
+++ b/docs/next/api/responses.md
@@ -51,28 +51,25 @@ JSON 正文使用 UTF-8。Tasks 成功响应省略无值可选字段,保留 0
## 错误响应
-主 API Server 和 Router 的错误响应采用下面的 OpenAI-compatible 结构。
+本地 API Server、Router 和 SaaS 的公共错误响应采用下面的统一结构。
独立 file_parse 使用 `error.code/message/upstream_status`,已有恢复记录时还返回状态字段;其错误格式以 [file_parse 错误响应](file-parse.md#错误响应) 为准。
```json
{
"error": {
- "type": "invalid_request_error",
"code": "task_already_terminal",
- "message": "Task is canceled",
- "param": null
+ "message": "Task is canceled"
}
}
```
| 字段 | 类型 | 必带 | 说明 |
|------|------|:--:|------|
-| `type` | string | 是 | 错误大类。 |
-| `code` | string 或 null | 是 | 机器可读的细分错误码,无具体错误码时为 `null`。 |
+| `code` | string | 是 | 稳定的非空错误码,供程序判断错误原因;不能省略或为 `null`。 |
| `message` | string | 是 | 人类可读描述,应包含必要上下文和修复建议。 |
-| `param` | string 或 null | 否 | 导致错误的参数名;本地 API 无具体参数时返回 `null`,Router 代理层自身错误也可能省略此字段。 |
+| `param` | string 或 null | 否 | 出错参数路径,例如 `files.0.page_range`;有明确对应参数时返回,无值时省略。接收端允许缺省或 `null`。 |
-上例对应 `409 Conflict`;HTTP 错误的正文类型为 `application/json`。当前 Python API Server 和 Router 的错误对象均包含 `type/code/message`,客户端将缺省的 `param` 按 `null` 处理。
+上例对应 `409 Conflict`;HTTP 错误的正文类型为 `application/json`。错误对象只包含必填 `code/message` 和可选 `param`,不再输出或接受 `type`。客户端依据 HTTP 状态与 `code` 处理请求失败,不解析 `message` 判断错误类别。
请求级错误位于顶层 `error`;异步解析失败则通常通过查询接口的 `200` 响应及 `files[].error` 表达,详见 [Tasks 错误响应](tasks.md#各接口错误响应)。
## 请求追踪
@@ -97,49 +94,40 @@ Idempotency-Key: 7f5b7f7c-5c5a-4b2f-bb89-0c901c9a2d6a
如果同一 key 被用于不同请求体,服务端应返回 `400 invalid_request`,避免客户端误以为复用了同一操作。
-## 错误类型
-
-| `type` | 含义 |
-|--------|------|
-| `invalid_request_error` | 请求参数非法、资源不存在或状态不允许。 |
-| `authentication_error` | API Key 无效或过期。 |
-| `permission_error` | 权限不足、配额耗尽或功能需要更高 access level。 |
-| `rate_limit_error` | 请求触发限流。 |
-| `engine_error` | 解析引擎不可用、崩溃或解析失败。 |
-| `timeout_error` | 请求等待或处理超时。 |
-| `internal_error` | 未归类异常的服务端内部错误;作为 `api_error` type 下的 code 出现(兜底 handler `api_server.py:2295-2305`),不是独立 type。 |
-| `api_error` | 服务端 API 层错误(存储、元数据、远端依赖等副作用失败),同时也是未归类异常兜底 handler 返回的 type。 |
-
## 常用错误码
-| HTTP | `type` | `code` |
-|------|--------|--------|
-| 400 | `invalid_request_error` | `invalid_request` |
-| 400 | `invalid_request_error` | `invalid_sha256sum` |
-| 400 | `invalid_request_error` | `file_hash_mismatch` |
-| 400 | `invalid_request_error` | `bytes_mismatch` |
-| 400 | `invalid_request_error` | `unsupported_parameter` |
-| 400 | `invalid_request_error` | `unsupported_output_format` |
-| 400 | `invalid_request_error` | `unsupported_source` |
-| 401 | `authentication_error` | `invalid_api_key` |
-| 403 | `permission_error` | `quota_exceeded` |
-| 403 | `permission_error` | `feature_requires_api_key` |
-| 403 | `permission_error` | `list_requires_api_key` |
-| 404 | `invalid_request_error` | `task_not_found`、`file_not_found`、`upload_not_found`、`model_not_found` |
-| 409 | `invalid_request_error` | `task_already_terminal`、`file_already_terminal` |
-| 410 | `invalid_request_error` | `upload_expired` |
-| 413 | `invalid_request_error` | `file_too_large` |
-| 429 | `rate_limit_error` | `rate_limit_exceeded` |
-| 500 | `api_error` | `internal_error` |
-| 503 | `api_error` | `service_unavailable` |
-| 503 | `api_error` 或 `engine_error` | `quality_tier_unavailable`,以具体入口返回的错误大类为准。 |
-
-完整错误分类见 [错误码体系](../errors.md)。
+| HTTP | `code` |
+|------|--------|
+| 400 | `invalid_request` |
+| 400 | `invalid_sha256sum` |
+| 400 | `file_hash_mismatch` |
+| 400 | `bytes_mismatch` |
+| 400 | `unsupported_parameter` |
+| 400 | `unsupported_output_format` |
+| 400 | `unsupported_source` |
+| 401 | `invalid_api_key` |
+| 403 | `quota_exceeded` |
+| 403 | `feature_requires_api_key` |
+| 403 | `list_requires_api_key` |
+| 404 | `task_not_found`、`file_not_found`、`upload_not_found`、`model_not_found` |
+| 409 | `task_already_terminal`、`file_already_terminal` |
+| 410 | `upload_expired` |
+| 413 | `file_too_large` |
+| 429 | `rate_limit_exceeded` |
+| 500 | `internal_error` |
+| 503 | `service_unavailable` |
+| 503 | `quality_tier_unavailable` |
+
+内部 CLI/Doclib 的错误分类见 [错误码体系](../errors.md),其中的 `type` 分类不属于公共解析 API 协议。
## 本地 Server 差异
-Local Parse Server 使用同一套错误 envelope。差异主要体现在错误来源:
+Local Parse Server 使用同一套错误结构。差异主要体现在错误来源:
- 未启用 API Key 时,不会产生 `invalid_api_key`。
- PDF/image 省略 `tier` 或传 `null` 且无法解析到非 `flash` 质量 tier 时,应返回 tier 相关错误,不能降级到 `flash`。OFD/EPUB/Office/HTML/MHTML/CSV 按 [ADR-0024](../decisions/0024-file-type-tier-normalization.md) 与 [ADR-0028](../decisions/0028-csv-structured-flash-parsing.md) 归一为 `flash`,其它 text 不作为解析输入。
-- 解析能力缺失时,应优先返回可操作的 `engine_error`,而不是泛化为 `internal_error`。
+- 解析能力缺失时,应返回具体的模型预加载或档位错误码,而不是泛化为 `internal_error`。
+
+## 协议升级
+
+本次是一次性协议升级:API、worker、Router、file_parse 和 SaaS 需协调切换,不支持新旧错误协议混用。切换前先收尾已受理任务。公共错误删除 `type`、要求非空 `code`,并统一省略空 `param`;内部 CLI/Doclib 分类与 file_parse 的历史恢复记录不随本次升级改写。
diff --git a/docs/next/api/tasks.md b/docs/next/api/tasks.md
index 682d2d40..6afcbb9f 100644
--- a/docs/next/api/tasks.md
+++ b/docs/next/api/tasks.md
@@ -290,13 +290,12 @@ SaaS 的上传目标可能是独立对象存储:通用客户端接受成功的
| 字段 | JSON 类型 | 必带 | 含义 |
|---|---|---|---|
-| `type` | string | 是 | 错误类型。 |
| `message` | string | 是 | 错误说明。 |
-| `code` | string | 否 | 具体错误码,有值时返回。 |
-| `param` | string | 否 | 关联参数,有值时返回。 |
+| `code` | string | 是 | 稳定的非空错误码,供程序判断错误原因。 |
+| `param` | string 或 null | 否 | 关联参数路径,例如 `files.0.page_range`;有值时返回,无值时省略。接收端允许缺省或 `null`。 |
-上表按成功快照说明,`code/param` 无值时省略。缺少顶层 `error` 不代表所有文件成功,`partial/failed` 的原因可能只在逐文件 `error` 中。
-HTTP 非成功响应也使用 `ErrorDetail`,但外层为 `{"error": ...}`,并保留各自的空值规则(`code/param` 可以为 `null`);完整示例及错误码见 [各接口错误响应](#各接口错误响应)。
+缺少顶层 `error` 不代表所有文件成功,`partial/failed` 的原因可能只在逐文件 `error` 中。
+HTTP 非成功响应也使用相同的 `ErrorDetail`,外层为 `{"error": ...}`。所有错误均不包含 `type`,`code/message` 必带,`param` 无值时省略;完整示例及错误码见 [各接口错误响应](#各接口错误响应)。
## 各接口成功响应
@@ -468,10 +467,8 @@ SaaS 的上传目标可能是独立对象存储:通用客户端接受成功的
```json
{
"error": {
- "type": "invalid_request_error",
"code": "task_already_terminal",
- "message": "Task is canceled",
- "param": null
+ "message": "Task is canceled"
}
}
```
@@ -490,7 +487,7 @@ SaaS 的上传目标可能是独立对象存储:通用客户端接受成功的
| 所有受保护接口 | 401 | `invalid_api_key` | 服务启用认证,但调用方未提供有效凭据。 |
Router 或网关还可能返回远端依赖相关的 5xx 错误;错误格式及部署扩展见 [响应与错误](responses.md)。
-本地 API 和上述任务错误示例包含 `param: null`;Router 代理层自身产生的错误也可能省略 `param`,客户端按 `null` 处理。
+本地 API、Router 和 SaaS 使用同一错误结构。`param` 只用于定位具体参数;没有对应参数时省略,客户端也接受 `null`。
异步文件下载、解析或导出失败通常通过查询接口的 **`200` 快照和 `files[].error`** 表达;不要把 HTTP `200` 等同于任务成功,也不要仅凭顶层 `error` 判断全部文件是否成功。
## URL、缓存与独立上传
diff --git a/docs/next/api/usage-limits.md b/docs/next/api/usage-limits.md
index 841725a9..4c0d5075 100644
--- a/docs/next/api/usage-limits.md
+++ b/docs/next/api/usage-limits.md
@@ -56,10 +56,8 @@ Header 说明:
```json
{
"error": {
- "type": "rate_limit_error",
"code": "rate_limit_exceeded",
- "message": "Parse rate limit (5/min) exceeded. Retry in 12s.",
- "param": null
+ "message": "Parse rate limit (5/min) exceeded. Retry in 12s."
}
}
```
diff --git a/docs/next/errors.md b/docs/next/errors.md
index 168f52cf..ca1adc24 100644
--- a/docs/next/errors.md
+++ b/docs/next/errors.md
@@ -10,15 +10,15 @@
错误码体系负责统一 API、CLI 和 SDK 对错误的表达。调用方应该能稳定地区分请求校验、文件上传、认证配额、解析执行、任务生命周期、服务端异常和本地运行错误。
-解析 API 层的错误码由本地 parse-server 和 `mineru.net/api` 共用。CLI 透传 server 返回的错误;只有在连接建立前或通信层失败时,才产生 CLI 本地错误。CLI 本地错误仍使用同一套 `error` envelope,不另起一套错误码体系。
+解析 API 层的错误码由本地 parse-server 和 `mineru.net/api` 共用。公共 HTTP 错误协议以 [响应与错误](api/responses.md) 为准,只包含必填 `code/message` 和可选 `param`,不包含 `type`。CLI/Doclib 内部保留原有分类;本页的 `type` 与内部扩展字段不构成公共 API 字段承诺。
错误码也是 Agent 的控制协议。Agent 看到错误后,应能判断下一步是重试、启动 server、显式加 `--remote`、选择 `--tier flash`,还是停止并把问题交给用户。
## 2. 设计原则
-- API、CLI 和 SDK 共享同一套 `type + code`。
+- API、CLI 和 SDK 使用稳定的 `code` 判断错误,`type` 仅保留于内部 CLI/Doclib 分类。
- CLI 透传 server 返回的错误;只在调用 server 前或通信层产生本地错误。
-- 错误格式兼容 OpenAI API。
+- 公共 API 使用简化的统一错误结构,具体字段以 [响应与错误](api/responses.md) 为准。
- `message` 面向人类,`code`、`param`、`retryable` 和 `user_action` 面向程序。
- 不显式 `--remote` 时,不用错误恢复逻辑静默上传文档。
- PDF/image 的默认选择策略不能降级为 `flash`;找不到非 `flash` 质量 tier 时必须报错。OFD/EPUB/Office/HTML/MHTML/CSV/TSV 这类仅支持 flash tier 的输入归一规则见 [ADR-0024](decisions/0024-file-type-tier-normalization.md) 与 [ADR-0028](decisions/0028-csv-structured-flash-parsing.md)。其它文本文件无需解析,显式 parse 请求返回 `parse_not_required`。
@@ -26,7 +26,21 @@
## 3. 错误响应格式
-基础格式与 OpenAI 兼容:
+公共解析 API 示例:
+
+```json
+{
+ "error": {
+ "code": "page_range_invalid",
+ "message": "Invalid page range",
+ "param": "files.0.page_range"
+ }
+}
+```
+
+`code` 必须是非空字符串,`message` 必填,`param` 无值时省略;接收端允许 `param` 缺省或为 `null`。HTTP 错误和 Tasks 逐文件错误遵守同一结构。
+
+以下示例和字段表仅描述内部 CLI/Doclib 的错误分类及扩展设计,不用于校验公共 HTTP 响应:
```json
{
@@ -52,9 +66,9 @@
| `user_action` | string \| null | 建议 | Agent/CLI 可执行的下一步动作 |
| `docs_url` | string \| null | 否 | 指向错误说明或修复文档 |
-`retryable`、`user_action` 和 `docs_url` 是 MinerU 扩展字段。OpenAI-compatible 客户端可以忽略它们。
+`retryable`、`user_action` 和 `docs_url` 是内部扩展设计字段,不属于公共 API 的 `ErrorDetail`。
-## 4. Type 枚举
+## 4. 内部 Type 枚举
| type | 含义 | HTTP |
|------|------|------|
diff --git a/mineru/kit/router/app.py b/mineru/kit/router/app.py
index d5e2d3aa..446450cf 100644
--- a/mineru/kit/router/app.py
+++ b/mineru/kit/router/app.py
@@ -189,7 +189,7 @@ def create_app(
for file in payload.get("files") or []:
if file.get("status") != "completed":
file["status"] = "failed"
- file["error"] = {"type": "engine_error", "code": "engine_dead", "message": "Worker engine was replaced"}
+ file["error"] = {"code": "engine_dead", "message": "Worker engine was replaced"}
progress = payload.get("progress")
if isinstance(progress, dict):
progress["failed"] = progress.get("total", 0) - progress.get("completed", 0)
diff --git a/mineru/kit/router/proxy.py b/mineru/kit/router/proxy.py
index 33b9f6c2..2485df5e 100644
--- a/mineru/kit/router/proxy.py
+++ b/mineru/kit/router/proxy.py
@@ -11,6 +11,7 @@ import httpx
from fastapi import Request
from fastapi.responses import JSONResponse, Response, StreamingResponse
+from ...tasks.contracts import ErrorResponse
from .resources import ResourceRegistry
from .workers import WorkerPool, WorkerState
@@ -47,7 +48,6 @@ class RouterProxyError(RuntimeError):
def router_error_response(exc: RouterProxyError) -> JSONResponse:
"""把 RouterProxyError 转成统一 V1 error response。"""
error: dict[str, Any] = {
- "type": "api_error" if exc.status_code >= 500 else "invalid_request_error",
"code": exc.code,
"message": exc.message,
}
@@ -120,7 +120,7 @@ async def stream_upstream(
path: str,
*,
request: Request,
-) -> StreamingResponse:
+) -> Response:
"""以流式方式代理 upstream 文件内容并在完成后关闭响应。"""
upstream_request = pool.client.build_request(
method,
@@ -129,6 +129,12 @@ async def stream_upstream(
)
try:
upstream = await pool.client.send(upstream_request, stream=True)
+ if upstream.status_code >= 400:
+ try:
+ await upstream.aread()
+ return passthrough_response(upstream)
+ finally:
+ await upstream.aclose()
except httpx.TimeoutException as exc:
raise RouterProxyError(504, "upstream_timeout", f"Upstream {worker.worker_id} timed out") from exc
except httpx.HTTPError as exc:
@@ -154,7 +160,17 @@ async def stream_upstream(
def passthrough_response(upstream: httpx.Response) -> Response:
- """保留 upstream 状态、body 与安全响应头生成普通响应。"""
+ """保留成功响应,严格校验上游错误并省略空参数,避免转发旧协议或畸形错误。"""
+ if upstream.status_code >= 400:
+ try:
+ error = ErrorResponse.model_validate_json(upstream.content)
+ except ValueError as exc:
+ raise RouterProxyError(502, "invalid_upstream_response", "Upstream returned an invalid error response") from exc
+ headers = response_headers(upstream.headers)
+ # 错误正文已经解码并重新序列化,不能沿用上游的内容编码和媒体类型。
+ headers.pop("content-encoding", None)
+ headers.pop("content-type", None)
+ return JSONResponse(error.model_dump(exclude_none=True), status_code=upstream.status_code, headers=headers)
return Response(
content=upstream.content,
status_code=upstream.status_code,
diff --git a/mineru/kit/router/tasks.py b/mineru/kit/router/tasks.py
index f65197fa..4d4c935c 100644
--- a/mineru/kit/router/tasks.py
+++ b/mineru/kit/router/tasks.py
@@ -23,6 +23,7 @@ from ...tasks.contracts import (
CancelTaskResponse,
CreateTaskResponse,
ErrorDetail,
+ ErrorResponse,
TaskDetailResponse,
TaskFileInput,
TaskFileItem,
@@ -55,23 +56,15 @@ def _checked_json(response: httpx.Response) -> dict[str, Any]:
except ValueError:
raise_api_error(
response.status_code if response.status_code >= 400 else 502,
- error_type="api_error",
code="invalid_upstream_response",
message="Upstream did not return a JSON object",
)
if response.status_code >= 400:
- detail = payload.get("error") or {}
- raise ApiServerError(
- response.status_code,
- ErrorDetail.model_validate(
- {
- "type": detail.get("type", "api_error"),
- "code": detail.get("code", "upstream_error"),
- "message": detail.get("message", "Upstream request failed"),
- "param": detail.get("param"),
- }
- ),
- )
+ try:
+ error = ErrorResponse.model_validate(payload).error
+ except ValidationError:
+ raise_api_error(502, code="invalid_upstream_response", message="Upstream returned an invalid error response")
+ raise ApiServerError(response.status_code, error)
return payload
@@ -92,7 +85,7 @@ async def _worker_request(
pool, worker, method, path, request=request, content=content, json_body=json_body, headers=headers
)
except RouterProxyError as exc:
- raise_api_error(exc.status_code, error_type="api_error", code=exc.code, message=exc.message, param=exc.param)
+ raise_api_error(exc.status_code, code=exc.code, message=exc.message, param=exc.param)
def _worker_path(worker: WorkerState, url: str) -> str:
@@ -106,16 +99,16 @@ def _worker_path(worker: WorkerState, url: str) -> str:
prefix = base.path.rstrip("/")
if origin(base) != origin(target) or target.username or target.password or target.query or target.fragment:
- raise_api_error(502, error_type="api_error", code="invalid_upstream_response", message="Invalid worker resource URL")
+ raise_api_error(502, code="invalid_upstream_response", message="Invalid worker resource URL")
if prefix and not target.path.startswith(prefix + "/"):
- raise_api_error(502, error_type="api_error", code="invalid_upstream_response", message="Invalid worker resource path")
+ raise_api_error(502, code="invalid_upstream_response", message="Invalid worker resource path")
return target.path[len(prefix) :]
def _lost_execution(route: ExecutionRoute) -> TaskExecution:
"""worker 丢失时终结有类型快照,并保留既有资源计数与诊断缓存。"""
previous = route.state.execution
- error = ErrorDetail(type="engine_error", code="upstream_task_lost", message="Upstream task no longer exists")
+ error = ErrorDetail(code="upstream_task_lost", message="Upstream task no longer exists")
execution = replace(previous, status="failed", finished_at=utc_now_iso(), result_file_id=None, error=error)
payload = copy.deepcopy(route.payload or {})
payload.update(status="failed", finished_at=execution.finished_at)
@@ -158,31 +151,29 @@ async def read_task_execution(
try:
payload = TaskDetailResponse.model_validate(_checked_json(response))
except ValidationError as exc:
- raise_api_error(502, error_type="api_error", code="invalid_upstream_response", message=str(exc))
+ raise_api_error(502, code="invalid_upstream_response", message=str(exc))
if payload.task_id != route.upstream_id:
- raise_api_error(502, error_type="api_error", code="invalid_upstream_response", message="Upstream task ID changed")
+ raise_api_error(502, code="invalid_upstream_response", message="Upstream task ID changed")
if len(payload.files) != 1:
- raise_api_error(502, error_type="api_error", code="invalid_upstream_response", message="Expected one task file")
+ raise_api_error(502, code="invalid_upstream_response", message="Expected one task file")
if payload.status == "partial":
- raise_api_error(
- 502, error_type="api_error", code="invalid_upstream_response", message="Invalid single-file task status"
- )
+ raise_api_error(502, code="invalid_upstream_response", message="Invalid single-file task status")
(remote_file,) = payload.files
if remote_file.file_id != route.state.upstream_file_id or remote_file.file_name != route.state.execution.file_name:
- raise_api_error(502, error_type="api_error", code="invalid_upstream_response", message="Worker file identity changed")
+ raise_api_error(502, code="invalid_upstream_response", message="Worker file identity changed")
upstream_file_id = remote_file.file_id
public_file_id = route.state.execution.file_id
result_file_id: str | None = None
if remote_file.status == "completed":
result_url = remote_file.result_url
if not isinstance(result_url, str):
- raise_api_error(502, error_type="api_error", code="invalid_upstream_response", message="Missing result URL")
+ raise_api_error(502, code="invalid_upstream_response", message="Missing result URL")
resource_path = _worker_path(worker, result_url)
parts = resource_path.strip("/").split("/")
if len(parts) != 4 or parts[:2] != ["v1", "files"] or parts[-1] != "content":
- raise_api_error(502, error_type="api_error", code="invalid_upstream_response", message="Invalid result File URL")
+ raise_api_error(502, code="invalid_upstream_response", message="Invalid result File URL")
if unquote(parts[2]) != upstream_file_id:
- raise_api_error(502, error_type="api_error", code="invalid_upstream_response", message="Result file ID changed")
+ raise_api_error(502, code="invalid_upstream_response", message="Result file ID changed")
existing = registry.find_upstream("file", route.owner_scope, worker.worker_id, upstream_file_id)
if existing is None and not registry.is_file_reserved(public_file_id):
# 取消、删除或过期的结果不因迟到响应重新登记;父 Task 保持已经发布的终态。
@@ -200,13 +191,11 @@ async def read_task_execution(
)
require_worker_generation(worker, generation)
if metadata.get("id") != upstream_file_id or metadata.get("purpose") != "parse_output":
- raise_api_error(
- 502, error_type="api_error", code="invalid_upstream_response", message="Invalid result File metadata"
- )
+ raise_api_error(502, code="invalid_upstream_response", message="Invalid result File metadata")
result_file_id = rewrite_file_payload(metadata, worker, registry, route.owner_scope, public_id=public_file_id)["id"]
else:
if existing.public_id != public_file_id:
- raise_api_error(502, error_type="api_error", code="invalid_upstream_response", message="Public file ID changed")
+ raise_api_error(502, code="invalid_upstream_response", message="Public file ID changed")
result_file_id = existing.public_id
result_route = registry.find("file", result_file_id)
if result_route is not None:
@@ -302,7 +291,6 @@ class RouterTaskBackend:
if not candidates:
raise_api_error(
503,
- error_type="api_error",
code="quality_tier_unavailable",
message="No worker supports requested task formats",
)
@@ -363,19 +351,13 @@ class RouterTaskBackend:
require_worker_generation(worker, generation)
ready = TaskDetailResponse.model_validate(_checked_json(response))
if ready.task_id != upstream_id or len(ready.files) != 1:
- raise_api_error(
- 502, error_type="api_error", code="invalid_upstream_response", message="Worker inputs are not ready"
- )
+ raise_api_error(502, code="invalid_upstream_response", message="Worker inputs are not ready")
(remote_file,) = ready.files
if remote_file.file_id != upstream_file_id or remote_file.file_name != item.file_name:
- raise_api_error(
- 502, error_type="api_error", code="invalid_upstream_response", message="Worker input order changed"
- )
+ raise_api_error(502, code="invalid_upstream_response", message="Worker input order changed")
if item.url is not None:
if remote_file.upload is not None:
- raise_api_error(
- 502, error_type="api_error", code="invalid_upstream_response", message="URL input requests upload"
- )
+ raise_api_error(502, code="invalid_upstream_response", message="URL input requests upload")
return ready
if remote_file.status != "waiting-file":
return ready
@@ -395,9 +377,7 @@ class RouterTaskBackend:
required_task_outputs=set(options.output_formats),
)
if reservation is None:
- raise_api_error(
- 503, error_type="api_error", code="quality_tier_unavailable", message="No capable worker is available"
- )
+ raise_api_error(503, code="quality_tier_unavailable", message="No capable worker is available")
worker = reservation.worker
upstream_id: str | None = None
route: ExecutionRoute | None = None
@@ -447,27 +427,19 @@ class RouterTaskBackend:
)
route.lease.held = True
if len(created.files) != 1:
- raise_api_error(
- 502, error_type="api_error", code="invalid_upstream_response", message="Worker input order changed"
- )
+ raise_api_error(502, code="invalid_upstream_response", message="Worker input order changed")
(remote_file,) = created.files
if remote_file.file_name != item.file_name:
- raise_api_error(
- 502, error_type="api_error", code="invalid_upstream_response", message="Worker input order changed"
- )
+ raise_api_error(502, code="invalid_upstream_response", message="Worker input order changed")
route.state.upstream_file_id = remote_file.file_id
link = remote_file.upload
if link is not None:
if upload is None:
- raise_api_error(
- 502, error_type="api_error", code="invalid_upstream_response", message="Unexpected worker upload"
- )
+ raise_api_error(502, code="invalid_upstream_response", message="Unexpected worker upload")
resource_path = _worker_path(worker, link.url)
expected_path = f"/v1/tasks/{quote(upstream_id, safe='')}/uploads/{quote(remote_file.file_id, safe='')}"
if resource_path != expected_path:
- raise_api_error(
- 502, error_type="api_error", code="invalid_upstream_response", message="Invalid worker upload path"
- )
+ raise_api_error(502, code="invalid_upstream_response", message="Invalid worker upload path")
response = await _worker_request(
self.pool,
worker,
@@ -484,11 +456,10 @@ class RouterTaskBackend:
try:
acknowledged = UploadFileResponse.model_validate(_checked_json(response))
except ValidationError as exc:
- raise_api_error(502, error_type="api_error", code="invalid_upstream_response", message=str(exc))
+ raise_api_error(502, code="invalid_upstream_response", message=str(exc))
if acknowledged.task_id != upstream_id or acknowledged.file_id != remote_file.file_id:
raise_api_error(
502,
- error_type="api_error",
code="invalid_upstream_response",
message="Upload acknowledgement ID changed",
)
@@ -526,7 +497,7 @@ class RouterTaskBackend:
"""检查本调用方的公共执行映射,不能用其他调用方的任务探测 worker。"""
route = self.registry.find("job", task_id)
if route is None or route.owner_scope != self.owner_scope:
- raise_api_error(404, error_type="invalid_request_error", code="task_not_found", message=f"Task {task_id} not found")
+ raise_api_error(404, code="task_not_found", message=f"Task {task_id} not found")
return route
async def get(self, task_id: str) -> TaskExecution:
@@ -552,16 +523,12 @@ class RouterTaskBackend:
try:
canceled = CancelTaskResponse.model_validate(_checked_json(response))
except ValidationError as exc:
- raise_api_error(502, error_type="api_error", code="invalid_upstream_response", message=str(exc))
+ raise_api_error(502, code="invalid_upstream_response", message=str(exc))
if canceled.task_id != route.upstream_id or len(canceled.files) != 1:
- raise_api_error(
- 502, error_type="api_error", code="invalid_upstream_response", message="Cancellation file identity changed"
- )
+ raise_api_error(502, code="invalid_upstream_response", message="Cancellation file identity changed")
(remote_file,) = canceled.files
if remote_file.file_id != route.state.upstream_file_id or remote_file.file_name != route.state.execution.file_name:
- raise_api_error(
- 502, error_type="api_error", code="invalid_upstream_response", message="Cancellation file identity changed"
- )
+ raise_api_error(502, code="invalid_upstream_response", message="Cancellation file identity changed")
execution = await self.get(task_id)
if execution.status in TERMINAL_TASK_STATUSES:
route.state.release_reservation()
@@ -573,13 +540,13 @@ def install_task_error_handlers(app: FastAPI) -> None:
@app.exception_handler(ApiServerError)
async def task_error(_request: Request, exc: ApiServerError) -> JSONResponse:
"""保留共享错误的 HTTP 状态和明确错误码。"""
- return JSONResponse({"error": exc.error.model_dump()}, status_code=exc.status_code)
+ return JSONResponse({"error": exc.error.model_dump(exclude_none=True)}, status_code=exc.status_code)
@app.exception_handler(RequestValidationError)
async def validation_error(_request: Request, exc: RequestValidationError) -> JSONResponse:
"""把路径及 JSON 校验错误统一转换成 400。"""
return JSONResponse(
- {"error": {"type": "invalid_request_error", "code": "invalid_request", "message": str(exc)}},
+ {"error": {"code": "invalid_request", "message": str(exc)}},
status_code=400,
)
diff --git a/mineru/parser/api_server.py b/mineru/parser/api_server.py
index 9ccb6a92..8acaa497 100644
--- a/mineru/parser/api_server.py
+++ b/mineru/parser/api_server.py
@@ -123,20 +123,10 @@ _PYDANTIC_CONFIG = ConfigDict(extra="forbid")
def _error_response(status_code: int, error: ErrorDetail) -> JSONResponse:
return JSONResponse(
status_code=status_code,
- content=ErrorResponse(error=error).model_dump(by_alias=True),
+ content=ErrorResponse(error=error).model_dump(by_alias=True, exclude_none=True),
)
-def _error_type_for_status(status_code: int) -> str:
- if status_code == 401:
- return "authentication_error"
- if status_code == 403:
- return "permission_error"
- if 400 <= status_code < 500:
- return "invalid_request_error"
- return "api_error"
-
-
def _validation_error_param(exc: RequestValidationError) -> str | None:
for err in exc.errors():
loc = err.get("loc", ())
@@ -179,7 +169,6 @@ def _http_exception_error(exc: HTTPException) -> ErrorDetail:
return ErrorDetail.model_validate(nested["error"])
message = str(detail) if detail else "HTTP error"
return ErrorDetail(
- type=_error_type_for_status(exc.status_code),
code="api_error" if exc.status_code >= 500 else "invalid_request",
message=message,
)
@@ -621,12 +610,11 @@ class FileStore:
if rec.purpose != "parse_output":
raise_api_error(
403,
- error_type="permission_error",
code="feature_requires_api_key",
message="Source files cannot be downloaded",
)
if rec.sha256sum is None or not self._blob_abs(rec.sha256sum).is_file():
- raise_api_error(404, error_type="invalid_request_error", code="file_not_found", message="Output expired")
+ raise_api_error(404, code="file_not_found", message="Output expired")
self._pins[rec.sha256sum] = self._pins.get(rec.sha256sum, 0) + 1
return self._blob_abs(rec.sha256sum), rec.filename, rec.sha256sum
@@ -669,7 +657,6 @@ class FileStore:
if rec is None or (rec.expires_at is not None and rec.expires_at <= int(time.time())):
raise_api_error(
404,
- error_type="invalid_request_error",
code="file_not_found",
message=f"File {file_id} not found",
)
@@ -693,14 +680,12 @@ class FileStore:
if rec.purpose != "parse_output":
raise_api_error(
403,
- error_type="permission_error",
code="feature_requires_api_key",
message="Source files cannot be downloaded",
)
if rec.sha256sum is None:
raise_api_error(
500,
- error_type="api_error",
code="internal_error",
message="File has no sha256sum",
)
@@ -711,7 +696,6 @@ class FileStore:
if file_id not in self._files:
raise_api_error(
404,
- error_type="invalid_request_error",
code="file_not_found",
message=f"File {file_id} not found",
)
@@ -767,7 +751,7 @@ def _validate_execution_source_policy(req: _ExecutionRequest, *, allow_http_sour
except ValueError as exc:
message = str(exc)
code = "unsupported_source" if "source" in message else "invalid_request"
- raise_api_error(400, error_type="invalid_request_error", code=code, message=message, param="files.0.source")
+ raise_api_error(400, code=code, message=message, param="files.0.source")
@dataclass
@@ -828,7 +812,7 @@ class ExecutionStore:
if task.done() or rec.status == "canceled":
continue
rec.status = "failed"
- rec.error = ErrorDetail(type="engine_error", code="engine_dead", message=message)
+ rec.error = ErrorDetail(code="engine_dead", message=message)
_discard_unfinished_output(rec)
if task is not current and not task.cancelling():
task.cancel()
@@ -838,7 +822,7 @@ class ExecutionStore:
message = self.runtime_owner.engine_error
if message is not None:
self.fail_engine(message)
- raise_api_error(503, error_type="engine_error", code="engine_dead", message=message)
+ raise_api_error(503, code="engine_dead", message=message)
def start_task(
self,
@@ -850,7 +834,7 @@ class ExecutionStore:
"""保存真实后台任务及所属应用租约,排队取消也不会开始解析。"""
self.require_ready()
if self._closing:
- raise_api_error(503, error_type="engine_error", code="server_shutting_down", message="Server is shutting down")
+ raise_api_error(503, code="server_shutting_down", message="Server is shutting down")
self._completion_events[rec.id] = asyncio.Event()
async def run_owned() -> None:
@@ -939,7 +923,7 @@ class ExecutionStore:
raise ValueError("_ExecutionRequest.tier must be resolved before execution creation")
execution_id = execution_id or new_execution_id()
if execution_id in self._executions:
- raise_api_error(409, error_type="invalid_request_error", code="job_already_exists", message="Job already exists")
+ raise_api_error(409, code="job_already_exists", message="Job already exists")
rec = _ExecutionRecord(
id=execution_id,
request=req,
@@ -984,7 +968,6 @@ class ExecutionStore:
if rec is None:
raise_api_error(
404,
- error_type="invalid_request_error",
code="job_not_found",
message=f"Job {job_id} not found",
)
@@ -996,7 +979,6 @@ class ExecutionStore:
if rec.status in ("completed", "failed", "canceled"):
raise_api_error(
409,
- error_type="invalid_request_error",
code="job_already_terminal",
message=f"Job is {rec.status}",
)
@@ -1141,9 +1123,9 @@ async def _prepare_execution_input(
return
rec.status = "failed"
rec.error = (
- ErrorDetail(type=exc.type, code=exc.code, message=str(exc), param=exc.param)
+ ErrorDetail(code=exc.code, message=str(exc), param=exc.param)
if isinstance(exc, MineruError)
- else ErrorDetail(type="engine_error", code="parse_failed", message=str(exc))
+ else ErrorDetail(code="parse_failed", message=str(exc))
)
@@ -1309,9 +1291,9 @@ async def _run_execution(
)
rec.status = "failed"
rec.error = (
- ErrorDetail(type=exc.type, code=exc.code, message=str(exc), param=exc.param)
+ ErrorDetail(code=exc.code, message=str(exc), param=exc.param)
if isinstance(exc, MineruError)
- else ErrorDetail(type="engine_error", code="parse_failed", message=str(exc))
+ else ErrorDetail(code="parse_failed", message=str(exc))
)
finally:
rec.finished_at = execution_timestamp()
@@ -1370,7 +1352,6 @@ def _require_model_preload_ready(request: Request) -> None:
return
raise_api_error(
503,
- error_type="engine_error",
code=preload_error.code,
message=preload_error.message,
)
@@ -1429,7 +1410,6 @@ async def get_model(
if model not in model_ids:
raise_api_error(
404,
- error_type="invalid_request_error",
code="model_not_found",
message=f"Model '{model}' not found",
)
@@ -1538,7 +1518,7 @@ async def submit_execution(
try:
body.page_range = normalize_page_range_input(body.page_range) or None
except MineruError as exc:
- raise_api_error(400, error_type=exc.type, code=exc.code, message=str(exc), param="files.0.page_range")
+ raise_api_error(400, code=exc.code, message=str(exc), param="files.0.page_range")
_require_model_preload_ready(request)
default_tier: Tier | None = request.app.state.default_tier
can_default_to_flash = _execution_can_default_to_flash(body)
@@ -1551,7 +1531,6 @@ async def submit_execution(
else:
raise_api_error(
503,
- error_type="engine_error",
code="quality_tier_unavailable",
message=(
"No basic, standard, or advanced tier available in this server. "
@@ -1568,13 +1547,12 @@ async def submit_execution(
if runtime is None:
raise_api_error(
400,
- error_type="invalid_request_error",
code="invalid_request",
message=f"Tier '{body.tier}' not available in this server",
)
_validate_execution_source_policy(body, allow_http_source=request.app.state.allow_http_source)
if execution_store._closing:
- raise_api_error(503, error_type="engine_error", code="server_shutting_down", message="Server is shutting down")
+ raise_api_error(503, code="server_shutting_down", message="Server is shutting down")
rec = execution_store.create(body, file_store, execution_id=execution_id)
rec.retention_held = True
url_timeout_val: int = request.app.state.url_timeout
@@ -2012,7 +1990,6 @@ def create_app(
return _error_response(
400,
ErrorDetail(
- type="invalid_request_error",
code=_validation_error_code(exc),
message=_validation_error_message(exc),
param=_validation_error_param(exc),
@@ -2029,7 +2006,6 @@ def create_app(
return _error_response(
500,
ErrorDetail(
- type="api_error",
code="internal_error",
message="Internal server error",
),
@@ -2053,7 +2029,6 @@ def create_app(
return _error_response(
401,
ErrorDetail(
- type="authentication_error",
code="invalid_api_key",
message="Invalid or missing API key",
),
diff --git a/mineru/tasks/contracts.py b/mineru/tasks/contracts.py
index 197fb69f..c41ff9ed 100644
--- a/mineru/tasks/contracts.py
+++ b/mineru/tasks/contracts.py
@@ -15,9 +15,10 @@ _PYDANTIC_CONFIG = ConfigDict(extra="forbid")
class ErrorDetail(BaseModel):
+ """公共错误只使用稳定错误码和说明,可选参数路径用于精确定位输入。"""
+
model_config = _PYDANTIC_CONFIG
- type: str
- code: str | None = None
+ code: str = Field(min_length=1)
message: str
param: str | None = None
diff --git a/mineru/tasks/errors.py b/mineru/tasks/errors.py
index 9a5b5f3b..6a8a9576 100644
--- a/mineru/tasks/errors.py
+++ b/mineru/tasks/errors.py
@@ -20,16 +20,14 @@ class ApiServerError(Exception):
def raise_api_error(
status_code: int,
*,
- error_type: str,
- code: str | None,
+ code: str,
message: str,
param: str | None = None,
) -> NoReturn:
- """统一构造并抛出已有错误信封,不改变字段或状态码。"""
+ """使用稳定错误码、说明和可选参数路径构造公共错误,保留 HTTP 状态。"""
raise ApiServerError(
status_code,
ErrorDetail(
- type=error_type,
code=code,
message=message,
param=param,
@@ -43,7 +41,6 @@ def invalid_task_request(
"""把协议校验错误转换成两类服务共用的 V1 error envelope。"""
raise_api_error(
status_code,
- error_type="api_error" if status_code >= 500 else "invalid_request_error",
code=code,
message=message,
param=param,
diff --git a/mineru/tasks/service.py b/mineru/tasks/service.py
index 262f99e7..c0c24b00 100644
--- a/mineru/tasks/service.py
+++ b/mineru/tasks/service.py
@@ -199,7 +199,7 @@ class TaskStore:
if item.url is None and file.upload is None and file.status == "waiting-file" and not file.upload_active:
file.expired = True
file.status = "failed"
- file.error = ErrorDetail(type="invalid_request_error", code="upload_expired", message="Upload expired")
+ file.error = ErrorDetail(code="upload_expired", message="Upload expired")
self._aggregate(record)
def collect_expired(self) -> None:
@@ -345,7 +345,7 @@ class TaskStore:
file.error = (
result.error
if isinstance(result, ApiServerError)
- else ErrorDetail(type="api_error", code="task_refresh_failed", message=str(result))
+ else ErrorDetail(code="task_refresh_failed", message=str(result))
)
if file.operation is not None:
file.operation.cancel()
@@ -387,7 +387,7 @@ class TaskStore:
file.error = (
exc.error
if isinstance(exc, ApiServerError)
- else ErrorDetail(type="api_error", code="task_submission_failed", message=str(exc))
+ else ErrorDetail(code="task_submission_failed", message=str(exc))
)
if file.status != "completed":
file.backend.discard_file_id(file.file_id)
diff --git a/tests/unittest/test_api_error_contract.py b/tests/unittest/test_api_error_contract.py
new file mode 100644
index 00000000..ea878e2c
--- /dev/null
+++ b/tests/unittest/test_api_error_contract.py
@@ -0,0 +1,235 @@
+"""公共错误协议在本地、代理和级联部署中的结构与失败处理回归。"""
+
+from __future__ import annotations
+
+import asyncio
+import gzip
+import json
+from pathlib import Path
+from collections.abc import AsyncIterator
+from types import SimpleNamespace
+from typing import Any
+
+import httpx
+import pytest
+from fastapi import Request
+from fastapi.testclient import TestClient
+from pydantic import ValidationError
+from test_task_tiers import _deployment
+
+from mineru.errors import MineruError
+from mineru.kit.router.proxy import RouterProxyError, passthrough_response, stream_upstream
+from mineru.kit.router.tasks import _checked_json
+from mineru.parser import api_server
+from mineru.parser.base import ParseResult
+from mineru.tasks.contracts import ErrorDetail, ErrorResponse
+from mineru.tasks.errors import ApiServerError
+
+
+ "payload",
+ [
+ {},
+ {"error": None},
+ {"error": []},
+ {"error": {"message": "Missing code"}},
+ {"error": {"code": None, "message": "Null code"}},
+ {"error": {"code": "", "message": "Empty code"}},
+ {"error": {"code": 123, "message": "Numeric code"}},
+ {"error": {"code": "invalid_request"}},
+ {"error": {"code": "invalid_request", "message": None}},
+ {"error": {"code": "invalid_request", "message": "Bad param", "param": []}},
+ {"error": {"code": "invalid_request", "message": "Old schema", "type": "invalid_request_error"}},
+ {"error": {"code": "invalid_request", "message": "Conflicting response"}, "task_id": "task-1"},
+ ],
+)
+def test_malformed_upstream_errors_are_protocol_errors(payload: dict[str, Any]) -> None:
+ """缺少字段、旧字段和矛盾响应必须被拒绝,Router 不补造业务错误或泄漏校验异常。"""
+ with pytest.raises(ValidationError):
+ ErrorResponse.model_validate(payload)
+ response = httpx.Response(400, json=payload)
+ with pytest.raises(ApiServerError) as task_error:
+ _checked_json(response)
+ assert task_error.value.status_code == 502
+ assert task_error.value.error.code == "invalid_upstream_response"
+ with pytest.raises(RouterProxyError) as proxy_error:
+ passthrough_response(response)
+ assert proxy_error.value.status_code == 502
+ assert proxy_error.value.code == "invalid_upstream_response"
+
+
[email protected]("fields", [{}, {"param": None}, {"param": "files.0.page_range"}])
+def test_upstream_error_normalization_preserves_http_and_param(fields: dict[str, Any]) -> None:
+ """普通代理和任务代理保留有效错误,重新编码正文时清除压缩头并统一省略空参数。"""
+ detail = {"code": "page_range_invalid", "message": "Invalid page range", **fields}
+ response = httpx.Response(
+ 400,
+ content=gzip.compress(json.dumps({"error": detail}).encode()),
+ headers={"content-encoding": "gzip", "content-type": "application/json", "x-request-id": "request-1"},
+ )
+ expected = {key: value for key, value in detail.items() if value is not None}
+ with pytest.raises(ApiServerError) as task_error:
+ _checked_json(response)
+ assert task_error.value.status_code == 400
+ assert task_error.value.error.model_dump(exclude_none=True) == expected
+ forwarded = passthrough_response(response)
+ assert forwarded.status_code == 400
+ assert json.loads(forwarded.body) == {"error": expected}
+ assert forwarded.headers["x-request-id"] == "request-1"
+ assert forwarded.headers["content-type"] == "application/json"
+ assert "content-encoding" not in forwarded.headers
+
+
[email protected]("outcome", ["valid", "malformed", "timeout", "disconnected"])
+def test_download_proxy_validates_errors_and_closes_upstream(outcome: str) -> None:
+ """下载代理遇到错误先验证正文并关闭上游,畸形正文不继续以文件流返回。"""
+ closed: list[bool] = []
+ payload = b"not json" if outcome == "malformed" else b'{"error":{"code":"file_not_found","message":"Expired","param":null}}'
+
+ class ErrorStream(httpx.AsyncByteStream):
+ """记录下载错误流是否按时关闭,防止异常分支泄漏连接。"""
+
+ async def __aiter__(self) -> AsyncIterator[bytes]:
+ """返回受控的上游错误正文,或模拟读取失败。"""
+ if outcome == "timeout":
+ raise httpx.ReadTimeout("Upstream timed out")
+ if outcome == "disconnected":
+ raise httpx.ReadError("Upstream disconnected")
+ yield payload
+
+ async def aclose(self) -> None:
+ """记录上游资源关闭。"""
+ closed.append(True)
+
+ async def scenario() -> None:
+ """只替换网络传输,运行真实的下载代理与结构校验。"""
+ transport = httpx.MockTransport(lambda _: httpx.Response(404, stream=ErrorStream()))
+ async with httpx.AsyncClient(transport=transport) as client:
+ pool = SimpleNamespace(client=client)
+ worker = SimpleNamespace(base_url="http://worker", worker_id="worker")
+ request = Request({"type": "http", "headers": []})
+ if outcome != "valid":
+ with pytest.raises(RouterProxyError) as error:
+ await stream_upstream(pool, worker, "GET", "/v1/files/file-1/content", request=request)
+ assert error.value.status_code == (504 if outcome == "timeout" else 502)
+ assert (
+ error.value.code
+ == {
+ "malformed": "invalid_upstream_response",
+ "timeout": "upstream_timeout",
+ "disconnected": "upstream_unavailable",
+ }[outcome]
+ )
+ else:
+ response = await stream_upstream(pool, worker, "GET", "/v1/files/file-1/content", request=request)
+ assert response.status_code == 404
+ assert json.loads(response.body) == {"error": {"code": "file_not_found", "message": "Expired"}}
+ assert closed == [True]
+
+ asyncio.run(scenario())
+
+
+def test_authentication_errors_use_public_contract(tmp_path: Path) -> None:
+ """认证中间件也使用简化协议,认证成功后仍保留资源不存在的状态码。"""
+ app = api_server.create_app(upload_dir=str(tmp_path), tiers=("flash",), api_key="secret")
+ with TestClient(app) as client:
+ unauthorized = client.get("/v1/tasks/missing")
+ assert unauthorized.status_code == 401
+ assert unauthorized.json() == {"error": {"code": "invalid_api_key", "message": "Invalid or missing API key"}}
+ missing = client.get("/v1/tasks/missing", headers={"Authorization": "Bearer secret"})
+ assert missing.status_code == 404
+ assert set(missing.json()["error"]) == {"code", "message"}
+
+
[email protected]("deployment", ["api", "router", "cascade"])
+def test_public_error_schema_and_request_failures(tmp_path: Path, deployment: str) -> None:
+ """真实请求覆盖校验、缺失资源、上传和重复取消,OpenAPI 与输出字段保持一致。"""
+
+ async def scenario() -> None:
+ """复用真实服务生命周期,在每一层验证相同的错误字段约束。"""
+ async with _deployment(tmp_path, deployment, {"worker": ("flash",)}) as (client, _app, _apps, _submissions):
+ schema = (await client.get("/openapi.json")).json()["components"]["schemas"]["ErrorDetail"]
+ assert set(schema["properties"]) == {"code", "message", "param"}
+ assert set(schema["required"]) == {"code", "message"}
+ assert schema["properties"]["code"]["minLength"] == 1
+ assert schema["additionalProperties"] is False
+ invalid = await client.post("/v1/tasks", json={"files": []})
+ assert invalid.status_code == 400
+ assert invalid.json()["error"]["param"] == "files"
+ assert "type" not in invalid.json()["error"]
+ for path, method, code in (
+ ("/v1/tasks/missing", "GET", "task_not_found"),
+ ("/v1/tasks/missing/cancel", "POST", "task_not_found"),
+ ("/v1/files/missing", "GET", "file_not_found"),
+ ("/v1/files/missing/content", "GET", "file_not_found"),
+ ):
+ missing = await client.request(method, path)
+ assert missing.status_code == 404, missing.text
+ assert set(missing.json()["error"]) == {"code", "message"}
+ assert missing.json()["error"]["code"] == code
+ created = await client.post("/v1/tasks", json={"files": [{"file_name": "a.html", "bytes": 3}]})
+ assert created.status_code == 202, created.text
+ task = created.json()
+ upload = task["files"][0]["upload"]
+ bad_upload = await client.put(upload["url"], content=b"x", headers=upload["headers"])
+ assert bad_upload.status_code == 400, bad_upload.text
+ assert bad_upload.json()["error"]["code"] == "upload_size_mismatch"
+ assert set(bad_upload.json()["error"]) == {"code", "message"}
+ path = f"/v1/tasks/{task['task_id']}/cancel"
+ assert (await client.post(path)).status_code == 200
+ conflict = await client.post(path)
+ assert conflict.status_code == 409
+ assert conflict.json()["error"]["code"] == "task_already_terminal"
+ assert set(conflict.json()["error"]) == {"code", "message"}
+
+ asyncio.run(scenario())
+
+
[email protected]("deployment", ["api", "router", "cascade"])
[email protected]("structured", [False, True])
+def test_file_errors_survive_query_and_cancel(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, deployment: str, structured: bool
+) -> None:
+ """解析失败经过逐跳查询和取消仍保留错误原因,未上传文件可独立取消。"""
+ detail: dict[str, str] = {"code": "parse_failed", "message": "Cannot parse input"}
+ if structured:
+ detail = {"code": "page_range_invalid", "message": "Invalid page range", "param": "files.0.page_range"}
+
+ async def fail_parse(path: str, **kwargs: Any) -> ParseResult:
+ """在真实执行出口注入业务异常或通用异常,保留完整上传、调度和查询流程。"""
+ if structured:
+ raise MineruError(detail["code"], detail["message"], param=detail["param"])
+ raise RuntimeError(detail["message"])
+
+ monkeypatch.setattr(api_server, "parse_async", fail_parse)
+
+ async def scenario() -> None:
+ """第一文件失败后取消仍在等待上传的第二文件,同时检查父任务错误序列化。"""
+ async with _deployment(tmp_path, deployment, {"worker": ("flash",)}) as (client, app, _apps, _submissions):
+ data = b"<html><body>input</body></html>"
+ created = await client.post(
+ "/v1/tasks",
+ json={"files": [{"file_name": name, "bytes": len(data)} for name in ("a.html", "b.html")]},
+ )
+ assert created.status_code == 202, created.text
+ task = created.json()
+ upload = task["files"][0]["upload"]
+ assert (await client.put(upload["url"], content=data, headers=upload["headers"])).status_code == 200
+ path = f"/v1/tasks/{task['task_id']}"
+ async with asyncio.timeout(10):
+ while True:
+ response = await client.get(path)
+ assert response.status_code == 200, response.text
+ snapshot = response.json()
+ if snapshot["files"][0]["status"] == "failed":
+ break
+ await asyncio.sleep(0.01)
+ assert snapshot["files"][0]["error"] == detail
+ app.state.task_store._records[task["task_id"]].error = ErrorDetail(code="task_refresh_failed", message="Task error")
+ assert (await client.get(path)).json()["error"] == {"code": "task_refresh_failed", "message": "Task error"}
+ canceled = await client.post(path + "/cancel")
+ assert canceled.status_code == 200, canceled.text
+ assert canceled.json()["files"][0]["error"] == detail
+ assert canceled.json()["files"][1]["status"] == "canceled"
+
+ asyncio.run(scenario())
diff --git a/tests/unittest/test_file_parse.py b/tests/unittest/test_file_parse.py
index 21dfc173..56d995a1 100644
--- a/tests/unittest/test_file_parse.py
+++ b/tests/unittest/test_file_parse.py
@@ -387,14 +387,18 @@ def test_real_task_tier_rejection_is_failed_and_not_replayed(
"status,payload",
[
(503, b"<html>Service unavailable</html>"),
- (503, {"error": {"type": "api_error", "code": "temporary", "message": "Try later"}}),
- (503, {"error": {"code": "quality_tier_unavailable", "message": "Missing required error type"}}),
+ (503, {"error": {"code": "temporary", "message": "Try later"}}),
+ (503, {"error": {"code": "quality_tier_unavailable"}}),
+ (503, {"error": {"message": "Missing error code"}}),
+ (503, {"error": {"code": None, "message": "Null error code"}}),
+ (503, {"error": {"code": "", "message": "Empty error code"}}),
+ (503, {"error": {"type": "api_error", "code": "quality_tier_unavailable", "message": "Legacy error type"}}),
(
503,
- {"task_id": "maybe-created", "error": {"type": "api_error", "code": "quality_tier_unavailable", "message": "x"}},
+ {"task_id": "maybe-created", "error": {"code": "quality_tier_unavailable", "message": "x"}},
),
- (500, {"error": {"type": "api_error", "code": "quality_tier_unavailable", "message": "Unexpected status"}}),
- (408, {"error": {"type": "api_error", "code": "quality_tier_unavailable", "message": "Timed out"}}),
+ (500, {"error": {"code": "quality_tier_unavailable", "message": "Unexpected status"}}),
+ (408, {"error": {"code": "quality_tier_unavailable", "message": "Timed out"}}),
],
)
def test_ambiguous_creation_errors_remain_unknown(tmp_path: Path, status: int, payload: bytes | dict[str, Any]) -> None:
diff --git a/tests/unittest/test_parser_api_contract.py b/tests/unittest/test_parser_api_contract.py
index 0cf3267b..7cc40f46 100644
--- a/tests/unittest/test_parser_api_contract.py
+++ b/tests/unittest/test_parser_api_contract.py
@@ -497,7 +497,6 @@ def test_api_client_preserves_structured_error_body_on_http_error() -> None:
401,
{
"error": {
- "type": "authentication_error",
"code": "invalid_api_key",
"message": "Invalid or missing API key",
"param": "api_key",
@@ -588,7 +587,7 @@ def test_api_server_validation_errors_use_error_envelope(tmp_path: Path, monkeyp
assert response.status_code == 400
body = response.json()
assert "detail" not in body
- assert body.get("error")["type"] == "invalid_request_error"
+ assert "type" not in body["error"]
assert body.get("error")["code"] == "invalid_request"
assert "Invalid request" in body.get("error")["message"]
@@ -609,10 +608,8 @@ def test_api_server_unhandled_exceptions_use_error_envelope(tmp_path: Path, monk
body = response.json()
assert "detail" not in body
assert body.get("error") == {
- "type": "api_error",
"code": "internal_error",
"message": "Internal server error",
- "param": None,
}
@@ -892,6 +889,8 @@ def test_api_server_model_preload_failure_keeps_health_diagnostics_and_rejects_c
assert tiers_response.json().get("error")["code"] == "model_preload_device_unavailable"
assert models_response.status_code == 503
assert models_response.json().get("error")["code"] == "model_preload_device_unavailable"
+ for response in (health_response, tiers_response, models_response):
+ assert set(response.json()["error"]) == {"code", "message"}
def test_api_server_model_preload_is_opt_in_and_ignored_for_flash(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
diff --git a/tests/unittest/test_router_balancing.py b/tests/unittest/test_router_balancing.py
index 66911249..c3fa1b3a 100644
--- a/tests/unittest/test_router_balancing.py
+++ b/tests/unittest/test_router_balancing.py
@@ -61,7 +61,6 @@ def test_task_auth_preflight_uses_a_capable_worker_without_reservation() -> None
401,
json={
"error": {
- "type": "authentication_error",
"code": "invalid_api_key",
"message": "Invalid key",
}
diff --git a/tests/unittest/test_task_tiers.py b/tests/unittest/test_task_tiers.py
index 0d3a392f..b8f23967 100644
--- a/tests/unittest/test_task_tiers.py
+++ b/tests/unittest/test_task_tiers.py
@@ -224,7 +224,11 @@ def test_task_tier_preflight_and_schema(
record = app.state.task_store._records[response.json()["task_id"]]
assert record.options.tier == ("standard" if "standard" in tiers else "flash")
else:
- assert response.json()["error"]["param"] == param
+ assert "type" not in response.json()["error"]
+ if param is None:
+ assert "param" not in response.json()["error"]
+ else:
+ assert response.json()["error"]["param"] == param
assert response.json()["error"]["code"] == ("quality_tier_unavailable" if status == 503 else "invalid_request")
assert all(not service.state.task_store._records for service in apps)
assert not submissions
diff --git a/tests/unittest/test_tasks_sdk.py b/tests/unittest/test_tasks_sdk.py
index 13bdcb0a..00c2d02a 100644
--- a/tests/unittest/test_tasks_sdk.py
+++ b/tests/unittest/test_tasks_sdk.py
@@ -302,18 +302,37 @@ def test_tasks_sdk_rejects_changed_identity(
@pytest.mark.parametrize("asynchronous", [False, True])
@pytest.mark.parametrize("state", ["failed", "canceled"])
[email protected]("fields", [{}, {"param": None}, {"param": "tier"}])
def test_tasks_sdk_preserves_file_errors(
- tmp_path: Path, monkeypatch: pytest.MonkeyPatch, asynchronous: bool, state: str
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, asynchronous: bool, state: str, fields: dict[str, Any]
) -> None:
"""优先保留逐文件错误码与字段,不统一改写为 parse_failed。"""
source = tmp_path / "file.pdf"
source.write_bytes(b"pdf")
snapshot = task_snapshot(state)
if state == "failed":
- snapshot["files"][0]["error"] = {"code": "engine_dead", "message": "engine stopped", "param": "tier"}
+ snapshot["files"][0]["error"] = {"code": "engine_dead", "message": "engine stopped", **fields}
bind_transport(monkeypatch, lambda _: httpx.Response(202, json=snapshot))
- with pytest.raises(api_client._V1APIError, match="engine_dead" if state == "failed" else "canceled"):
+ with pytest.raises(api_client._V1APIError, match="engine_dead" if state == "failed" else "canceled") as error:
parse(MinerUApiParser(api_url="https://api.test"), source, asynchronous)
+ assert error.value.param == (fields.get("param") if state == "failed" else None)
+
+
[email protected]("asynchronous", [False, True])
[email protected]("fields", [{}, {"param": None}, {"param": "api_key"}])
+def test_tasks_sdk_preserves_http_errors_without_type(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, asynchronous: bool, fields: dict[str, Any]
+) -> None:
+ """同步和异步入口都只依赖错误码和说明,可选字段缺省或为空时保持可用。"""
+ source = tmp_path / "file.pdf"
+ source.write_bytes(b"pdf")
+ detail = {"code": "invalid_api_key", "message": "Invalid API key", **fields}
+ bind_transport(monkeypatch, lambda _: httpx.Response(401, json={"error": detail}))
+ with pytest.raises(api_client._V1APIError) as error:
+ parse(MinerUApiParser(api_url="https://api.test"), source, asynchronous)
+ assert error.value.code == detail["code"]
+ assert error.value.message == detail["message"]
+ assert error.value.param == fields.get("param")
def test_task_output_preserves_middle_without_model_output(tmp_path: Path) -> None: