Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.
Python ai4sciencedocument-analysisdocxextract-datalayout-analysisocrparserpdfpdf-converterpdf-extractor-llmpdf-extractor-pretrainpdf-extractor-ragpdf-parserpptxpythonxlsx
refactor(api): simplify public error response contract
myhloli17caae651263
diff --git a/docs/next/api/README.md b/docs/next/api/README.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.pyindex 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.pyindex 33b9f6c2..2485df5e 100644--- a/mineru/kit/router/proxy.py+++ b/mineru/kit/router/proxy.py@@ -11,6 +11,7 @@ import httpxfrom fastapi import Requestfrom fastapi.responses import JSONResponse, Response, StreamingResponse+from ...tasks.contracts import ErrorResponsefrom .resources import ResourceRegistryfrom .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 excexcept 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.pyindex 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.filesif 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_idpublic_file_id = route.state.execution.file_idresult_file_id: str | None = Noneif remote_file.status == "completed":result_url = remote_file.result_urlif 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_idresult_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.filesif 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 readyif 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.workerupstream_id: str | None = Noneroute: ExecutionRoute | None = None@@ -447,27 +427,19 @@ class RouterTaskBackend:)route.lease.held = Trueif 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.filesif 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_idlink = remote_file.uploadif 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 routeasync 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.filesif 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.pyindex 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) + 1return 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_sourexcept 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":continuerec.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_errorif 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(returnrec.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:returnraise_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 Noneexcept 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_tiercan_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 = Trueurl_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.pyindex 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: strparam: str | None = Nonediff --git a/mineru/tasks/errors.py b/mineru/tasks/errors.pyindex 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.pyindex 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 = Truefile.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.errorif 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.errorif 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.pynew file mode 100644index 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.pyindex 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.pyindex 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, monkeypassert response.status_code == 400body = 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, monkbody = response.json()assert "detail" not in bodyassert 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_cassert tiers_response.json().get("error")["code"] == "model_preload_device_unavailable"assert models_response.status_code == 503assert 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.pyindex 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() -> None401,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.pyindex 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"] == paramassert 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 submissionsdiff --git a/tests/unittest/test_tasks_sdk.py b/tests/unittest/test_tasks_sdk.pyindex 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: