可当 API 文档

错误、限流与排查

根据状态码、错误详情和任务状态确定处理方式。

HTTP 状态与处理建议

下表使用 HTTP 通用语义。响应体的 error.code、error.type 或顶层 code 按接口原值读取；同一 HTTP 状态可能对应不同业务原因。具体错误码与字段位置见下方错误码参考。

HTTPcode一般含义处理建议重试条件
400—请求内容无效核对必填字段、类型、模型规格和参数层级。修正请求后再发。
401—认证失败核对 API Key、认证头以及令牌是否有效。更新认证信息后再发。
403—访问被拒绝检查令牌权限、分组与模型访问条件；按响应说明处理策略限制。权限或请求条件改变后再发。
404—资源或路径不存在检查域名、路径、模型 ID 或任务 ID；避免重复拼接 /v1。先确认正确资源。
408—请求超时核对请求大小、客户端网络和超时设置；创建任务时先查提交记录。确认可以安全重复后再试。
413—请求体过大压缩媒体、缩短输入或按所选模型的文件上限拆分。减小请求后再发。
422—请求字段无法处理检查字段组合、格式、取值范围与接口要求。修正字段后再发。
429—达到速率或配额限制结合错误信息区分 RPM、TPM、并发和余额/配额条件。速率限制按 Retry-After 退避；配额问题先处理配额。
500—服务处理异常保存请求标识，确认错误信息是否指出固定参数或配置问题。仅对暂时性故障有限重试。
502—网关获得无效上游响应保留请求标识；异步创建需先确认任务是否已受理。确认可重复后退避重试。
503—服务暂不可用结合 code/message 区分临时容量问题和模型、通道或权限配置问题。临时故障可退避；配置问题先修正。
504—网关等待上游超时检查已返回的任务 ID 或提交记录，避免重复生成。先查询已有任务，再决定是否重发。

错误码参考

按 HTTP 状态、错误码字段位置和 error.type 对照下表，再结合响应中的 message 处理。顶层 code 与嵌套的 error.code 应分别读取。下表为错误字段组合参考，并非完整错误枚举；相同 code 的 HTTP 状态或 error.type 可能因接口不同，以本次响应为准。model_not_found 的范围限于当前请求的模型、接口与权限条件。

HTTP错误码字段codeerror.type含义处理建议重试条件
400error.codeinvalid_requestkedang_api_error当前请求缺少参数，或参数规格不符合接口要求。按 message 核对必填参数、参数位置与模型规格。修正请求后重新提交。
400codefail_to_fetch_task—任务相关请求处理失败，具体原因由 message 给出。根据 message 修正参数或输入条件；若已有任务 ID，先查询原任务。先处理具体原因，避免直接重复创建任务。
503error.codemodel_not_foundkedang_api_error当前请求未匹配到可用模型。核对完整模型 ID、接口格式与令牌权限，并查阅平台当前模型目录。先确认模型与访问条件，避免仅因 HTTP 503 持续重试。

重试、流式与异步任务

  • 有限重试：仅对暂时性错误启用指数退避并加入随机抖动；若响应提供 Retry-After，优先遵循它。设置最大次数和总等待时限。
  • 避免重复创建：超时或断线不表示服务端未处理。已获得任务 ID 时，查询同一任务；没有 ID 时先核对提交记录。除非接口明确支持幂等机制，不应假定重复 POST 会自动去重。
  • 流式中断：已经收到部分输出时，记录中断位置并由应用决定恢复方式。重新请求可能产生新输出与新用量，不能简单拼接为同一响应。
  • 任务失败：创建成功只表示受理。继续解析任务状态与错误详情，完成后再读取结果；失败处理与返还口径见 计费口径。
  • 错误内容：即使 HTTP 返回 200，仍需按协议解析错误对象、流式错误事件或失败任务状态。

速率、并发与队列

RPM 表示每分钟请求数，TPM 表示每分钟 Token 数，并发表示同时处理的请求或任务数量。限制的作用范围、统计窗口和 Token 口径由平台配置决定。应用端可用队列控制并发，并为任务查询设置轮询间隔。

项目说明平台信息
限制范围账户、令牌、分组或模型等适用范围—
RPM每分钟请求上限—
TPM每分钟 Token 上限—
并发同时处理的请求或任务上限—
队列服务端排队容量及规则—
服务端超时服务端请求超时，秒—
任务查询间隔平台要求的最小轮询间隔，秒—
查询请求计数任务查询是否计入请求限额—

结果有效期

获得生成结果后，按业务需要保存文件与任务标识。临时地址、任务记录和结果文件可能有不同的有效期。

项目说明平台信息
结果地址有效期下载地址的有效时间及适用模型—
任务记录保留期任务状态与记录可查询的时间—
过期处理地址或任务记录过期后的处理方式—

提交排查信息

保留请求时间与时区、接口路径、模型 ID、HTTP 状态、错误 code/message，以及响应中存在的请求 ID 或任务 ID。附上去除 API Key 和敏感输入后的最小请求结构，便于定位认证、字段、模型配置或任务状态问题。