错误、限流与重试

错误格式

错误响应为 application/problem+json。请根据 HTTP 状态码判断，不要依赖 detail 文案。字段校验失败时，可能额外返回描述无效字段的 errors 数组。下面是错误结构示意：

{"status": 401, "detail": "请提供有效的 API Key"}

状态码	建议处理
400	修正 JSON 格式或任务、媒体参数
401	检查密钥、站点、过期与撤销状态
402	在工作台检查积分余额或账户限制
403	使用具备对应权限的密钥
404	检查 ID；不存在和他人资源均不会暴露
409	检查报价、幂等键或任务状态，不要直接重复提交
410	产物被删除，或原幂等任务已经清理
413	缩小上传文件或请求体
422	按接口字段契约修正参数
429	等待 Retry-After 指定时间并降低并发
500 / 502 / 503 / 504	使用带随机抖动的退避重试，保留提交的原键与请求体

重试同一个逻辑任务

第一次 POST /tasks 前持久化 Idempotency-Key 和请求体。连接超时或响应丢失时，使用同键同参数重试。同一账户内即使轮换 API Key，也会返回原任务；同键不同参数返回 409。JSON 的空白与属性顺序不影响幂等。

报价过期时，前一次提交仍可能已经成功，只是响应丢失：先重试原来的键和请求体以找回原任务。只有确认要创建新的逻辑任务时，才重新报价并换新键。任务清理后，旧键仍保留，重放返回 410。

不要对所有错误无条件重试。可重试故障使用有上限的指数退避与随机抖动，响应包含 Retry-After 时遵守它。客户端超时不会取消服务端任务。日志中不要记录 API Key 或签名文件 URL。

限流与轮询

每个密钥每分钟最多 120 次请求。同一 IP 一分钟内出现 20 次无效密钥尝试会被暂时限制。增加密钥数量不会提高账户处理并发、上传额度或余额。每两秒轮询一次，相当于每个活跃任务每分钟约 30 次请求；多个任务需要共享请求预算并延长轮询间隔。

费用与结果保留

报价不预留积分或算力。有效 quoteId 在过期前锁定报价，maxCostCredits 可再设置扣费上限。创建任务与预扣积分是原子操作，失败和取消按现有规则退款；取消已经成功的任务不会退款。

刷新签名结果链接不收费，删除的产物也不能靠刷新链接恢复。当前 API 不支持抓取任意远程输入 URL，也不支持 webhook 通知，请先上传文件，并轮询任务直到结束。