为保证计算资源的公平分配和后端服务的稳定性，DeckFlow 对文件处理、接口调用频率和配额做出了明确的限制。
1. 文件大小限制
不同接口与工具所支持的最大单文件大小限制如下。在调用任务创建接口前，请确保文件未超出以下阈值：
| 功能 / 工具分类 | 最大单文件大小 | 支持的输入格式 |
|---|---|---|
| 文档翻译 (Translate) | 500 MB | .pptx, .key, .pdf, .docx, .doc, .xlsx, .xls |
| 网页打包工具 (HTML Player Pack) | 50 MB | .html, .htm |
| HTML 转换器 (html2png / html2pptx) | 50 MB | .html, .htm (支持粘贴 HTML 代码) |
| Markdown 转换器 (markdown2png) | 10 MB | .md, .markdown (支持粘贴 Markdown 文本) |
| 图片 OCR 识别 (image.ocr) | 50 MB | image/* (如 JPG, PNG 等) |
| 图片尺寸修改 (image.resize) | 100 MB | image/* (如 JPG, PNG 等) |
| 图片转 WebP (image.convertWebp) | 100 MB | image/* (如 JPG, PNG 等) |
| 视频压缩工具 (video.compress) | 300 MB | video/* (如 MP4, MOV 等) |
| 其他文档与演示文稿工具 | 300 MB | .pptx, .ppt, .key, .docx, .doc, .xlsx, .xls, .pdf, .zip |
2. API 错误状态码
当 API 请求失败或创建任务报错时，接口将返回对应的 HTTP 状态码及 JSON 格式的错误详情。以下为系统通用的状态码规范：
| 状态码 | 错误代码 (code) | 描述 / 场景 | 推荐排查与故障恢复方案 |
|---|---|---|---|
400 | invalid_parameter | 请求参数缺失、值格式错误或不支持的文件格式。 | 检查并修正 POST /tools/tasks 中的 type 或 params 属性。 |
400 | file_size_exceeded | 上传的文件超出了上述单文件大小限制。 | 压缩文件体积，或分批次拆分文稿后重新提交。 |
401 | unauthorized | 缺少认证密钥，或 Authorization 头部格式不正确。 | 确认请求头格式为 Authorization: Bearer <YOUR_API_KEY>。 |
402 | insufficient_quota | 工作区内的 Credit 或 Spark 配额已用尽。 | 提示用户登录 DeckFlow 设置页面补充额度或升级套餐。 |
403 | forbidden | 密钥有效，但无权访问当前工作区、功能或目标 Space。 | 确认 spaceId 参数正确，并检查当前密钥的权限范围。 |
429 | rate_limit_exceeded | 接口并发调用超出了速率限制阈值。 | 实施客户端指数退避（Exponential Backoff）重试，降低请求并发。 |
5xx | internal_error | 服务器内部故障或临时网络错误。 | 可直接进行退避重试。 |
3. 任务重试策略
在程序处理 DeckFlow 后端响应时，请遵循以下重试逻辑：
- 可重试错误：
- HTTP
429(限流)：应等待并实施退避重试。 - HTTP
5xx(服务器临时故障)：建议在短时间延迟后自动重试。 - 不可重试错误：
- HTTP
400/401/403：通常是参数、授权或权限问题，重复请求将返回相同结果。必须在修改请求或修复权限后再重试。 - HTTP
402(配额耗尽)：必须在账户充值或购买配额后重新调用。