响应与错误码

标准错误结构

大多数新接口返回：

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "resource does not exist"
}

旧图片兼容接口只保证 code 和 message。

资源错误

HTTP	code	说明
404	RESOURCE_NOT_FOUND	token 不存在或已删除
409	RESOURCE_STATE_CONFLICT	资源不处于本次操作要求的状态
410	RESOURCE_EXPIRED	固定 TTL 已到期
422	INVALID_IMAGE_RESOURCE	图片不可读取、MIME 不一致或像素超限
503	RESOURCE_SERVICE_UNAVAILABLE	API 无法访问 Resource Service
507	RESOURCE_CAPACITY_EXCEEDED	Resource Service 容量耗尽

流与预览错误

HTTP	code	说明
404	STREAM_NOT_FOUND	流不存在，或预览源没有活动流
409	PREVIEW_SUPERSEDED	本批次被更新请求取代
410	STREAM_EXPIRED	流 TTL 已到期
429	STREAM_SUBSCRIBER_LIMIT	单流订阅者达到上限
503/507	STREAM_CAPACITY_EXCEEDED	流数量或最新帧内存容量耗尽
413	PREVIEW_FRAME_TOO_LARGE	Worker 预览帧超过下载限制

Worker 与渲染错误

HTTP	code	说明
400	INVALID_RENDER_JOB	请求字段或组合非法
429	WORKER_BUSY	Image Worker 达到并发上限
502	INVALID_WORKER_RESPONSE	Worker 返回空内容或错误 MIME
503	WORKER_UNAVAILABLE	Image Worker 未配置或网络不可达
504	WORKER_TIMEOUT	Worker 调用超时
413	FINAL_IMAGE_TOO_LARGE	单张最终图片超过限制
507	FINAL_RENDER_CAPACITY_EXCEEDED	API 最终渲染 tmpfs 预留容量耗尽

客户端处理建议

• 400/422：修正请求，不自动重试。
• 404/410：重新上传资源或创建流。
• 409 PREVIEW_SUPERSEDED：忽略旧请求结果。
• 429：指数退避并降低并发。
• 502/503/504：有限次数重试并记录依赖健康状态。
• 507：等待容量释放；持续出现时联系运维调整限制。

不要无限重试最终渲染。必须先确认资源仍为 READY，并为每次调用设置客户端超时和取消信号。