可灵 API 的失败大致分三层：请求层（HTTP 状态码与业务错误码）、任务层（task failed）、结果层（下载失败）。排查顺序应是：先看状态码和业务码，再看 request_id 与最小复现，最后才改参数或换模型。顺序反了，容易把配置问题当成模型能力问题。

本文以 2026 年 10 月可灵开放平台文档中的错误码和任务状态为例，给出排查顺序、重试与幂等建议。接口和错误码可能随版本调整，最终以官方文档为准。

说明：可灵/Kling 是快手及其关联公司的商标。本文仅作技术说明，不代表任何隶属或背书关系。错误码、并发规则和计费方式以官方文档与站内价格页为准。

一、三层失败先分清

请求层失败会立即返回：401 鉴权、400 参数、403 权限、429 限流或余额、5xx 服务端错误。任务层失败是提交成功、拿到任务 ID 之后，状态变成 failed，原因在 message 字段里。结果层失败则是任务已经 succeeded，但下载链接打不开、过期或被清理。

三层要分开记录。把任务失败当成鉴权失败反复换 Key，或者把下载失败当成生成失败重复提交，都会浪费时间和费用。

二、401 鉴权：1000–1004 逐个查

401 表示身份没有通过验证，和模型能力、余额通常无关。可灵文档给出的业务码是：1000 鉴权失败，1001 缺少 Authorization 字段，1002 Token 无效，1003 Token 尚未生效，1004 Token 已过期。

当前型号使用 API Key，放在 Authorization: Bearer 头里；旧版接口使用 AK/SK 签发 JWT，HS256 签名，有效期约 30 分钟。两种方式不能混用。按下面顺序排查：

  1. 请求头是否为 Authorization: Bearer <凭证>，Bearer 后是否有空格。
  2. 凭证前后是否有空格、换行或多余引号，从聊天窗口复制最容易带进来。
  3. 环境变量是否真的加载，可以只打印前缀确认，不要打印完整 Key。
  4. Key 是否被删除、轮换或停用；旧接口的 JWT 是否超过 30 分钟，或机器时钟偏差导致尚未生效。
  5. Base URL、区域域名和 Key 是否属于同一平台；海外服务器与国内平台不要混用地址。
  6. 反向代理是否覆盖或丢弃了 Authorization 头；回调签名密钥是否配置正确。
  7. 用一把新 Key 做最小请求，区分是凭证问题还是代理、网关配置问题。

三、429 与余额、并发：先分清限流类型

429 不一定都是“请求太快”。可灵文档中，1100 表示账号状态异常，1101 表示后付费欠费，1102 表示预付资源包用尽或过期，这三类都挂在 429 下；1302 是速率限制，1303 是并发超过资源包上限，1304 是 IP 白名单限制；1103 则是 403 无权限。

并发按账号、模型版本和资源包类型分别计算，同一账号下的所有 Key 共享额度。任务从 submitted 开始占用并发，直到成功或失败才释放；查询请求不占并发。因此多开几把 Key 并不能绕过并发上限。

处理方式：先读 message 和业务码，确认是余额、并发还是权限；对 1302、1303 做指数退避，首次等待不少于 1 秒，并把提交放进队列；持续超限时减少并发、错峰，或按实际用量调整资源包。不要用无退避的重试风暴去撞限流。

四、400/404 参数与模型错误：1200–1203

1200 是通用参数错误，1201 指向具体字段或取值错误，1202 是 HTTP 方法不对，1203 是资源或模型不存在。1300 表示请求与平台策略冲突，1301 表示输入触发内容安全策略，通常也是 400。

常见原因包括：时长超出型号范围（2.5 Turbo 只支持 5 秒或 10 秒，3.0 系列为 3–15 秒）；分辨率不支持（4K 只在部分型号提供）；比例、首尾帧、参考图数量与型号不匹配；图片 URL 无法被平台访问；模型版本没有写在路径或 model_name 中；提示词超过长度上限。

排查时先用最小请求复现，再逐项加回参数。内容审核拒绝不是技术故障，不要通过改关键词反复绕过。

五、任务 failed：状态、message 与回调

任务状态常见为 submitted、processing、succeeded、failed；旧版接口可能返回 succeed 而不是 succeeded，适配层要同时兼容。failed 时重点看 message、request_id 和提交参数。

常见失败原因：输入图片或视频下载失败、内容审核、上游渲染异常、任务超时、模型临时不可用。失败任务要保留记录，不要立刻删除，否则无法复盘。

如果使用 callback_url，要校验 webhook-id、webhook-timestamp 和 webhook-signature，签名用 HMAC-SHA256；测试回调每 6 秒最多一次，服务端成功处理应返回 HTTP 200。文档没有承诺回调失败一定重试，因此生产环境应保留轮询作为兜底，不能只依赖回调。

六、超时与轮询：不要把异步任务写成同步

视频任务从几十秒到几分钟都常见，高峰期还会排队。HTTP 客户端的连接超时、读取超时和任务总超时要分开设置：连接超时可以短，读取超时按查询接口设置，任务总超时按业务可接受时间设置。

轮询建议从 5 秒起步，逐步退避到 15–30 秒，并加入随机抖动；设置最大轮询次数和总截止时间，超时后标记为待确认，而不是无限等待。5xx 中的 5000、5001、5002 分别表示内部错误、服务暂不可用和上游超时，可以退避重试；401、403、1301 不应盲目重试。

下面是一段简化的 Python 示例，把提交、轮询、错误分类和下载串起来：

import time
import random
import requests

API_KEY = "你的可灵凭证"
BASE = "https://你的可灵接口地址"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def create_task(payload, external_id):
    payload = {**payload, "external_task_id": external_id}
    resp = requests.post(f"{BASE}/text-to-video/你的模型路径",
                         json=payload, headers=HEADERS, timeout=(5, 30))
    if resp.status_code == 401:
        raise RuntimeError("鉴权失败，检查 Key、Bearer 和区域")
    if resp.status_code == 429:
        raise RuntimeError(f"限流、余额或并发问题: {resp.text}")
    resp.raise_for_status()
    return resp.json()["data"]["id"]

def wait_and_download(task_id, timeout=900):
    deadline = time.time() + timeout
    delay = 5
    while time.time() < deadline:
        r = requests.get(f"{BASE}/tasks", params={"task_ids": task_id},
                         headers=HEADERS, timeout=(5, 30))
        if r.status_code in (500, 503, 504):
            time.sleep(delay + random.random())
            delay = min(delay * 1.5, 30)
            continue
        r.raise_for_status()
        task = r.json()["data"][0]
        status = task["status"].lower()
        if status in ("succeeded", "succeed"):
            url = task["outputs"][0]["url"]
            video = requests.get(url, timeout=(5, 120))
            video.raise_for_status()
            return video.content  # 生产环境应流式写入对象存储
        if status == "failed":
            raise RuntimeError(task.get("message") or "task failed")
        time.sleep(delay)
        delay = min(delay * 1.5, 30)
    raise TimeoutError(task_id)

# 重试提交前，先按 external_task_ids 查询任务是否已经创建

七、结果下载失败：链接有效期与转存

任务成功后，结果在 outputs 里，视频有 url、watermark_url 和 duration。文档说明生成结果会在 30 天后清理，链接也可能有更短的实际有效期。下载失败常见于：链接过期、任务结果被清理、网络超时、对象存储权限或代理拦截。

处理建议：成功后立即下载并转存到自己的对象存储；下载与生成分开重试，下载失败不要重新提交生成；记录 content-type、content-length 和校验值；不要把带签名的完整链接打进公开日志。如果结果已被清理，通常只能重新生成，因此转存要放在成功回调或轮询成功后的第一步。

八、重试与幂等：别让一次失败扣两次费

重试前先分类：429、5xx 和网络超时可以退避重试；400、401、403、1301 应先修问题，不要重试；任务 failed 要先看 message，修好原因再提交新任务。

可灵支持 external_task_id，且要求同一账号内唯一。提交时带上业务单号或幂等键，网络超时后先按 external_task_ids 查询，确认任务是否已经创建，再决定是否重发。否则一次“请求超时”可能变成两条任务、两次计费。

任务表至少记录：业务单号、task_id、external_id、模型与参数、状态、message、request_id、费用和重试次数。对账时按 task_id 去重，不要按提交次数统计。

九、一张排查顺序表

现象 先查什么 常见原因 处理
401 Authorization、Key、区域 1000–1004，JWT 过期或未生效 修凭证，做最小请求
429 业务码与 message 1101/1102 余额、1302 速率、1303 并发 充值、退避、降并发
400 参数与内容 1200/1201/1300/1301 按 message 修参数，审核拒绝不绕过
404 路径、方法、模型 1202/1203 对照文档改路径和模型名
failed message、输入素材 下载失败、审核、渲染异常 修素材或参数，保留记录
超时 连接/读取/任务超时 排队、长任务、上游 5xx 分层设置超时，退避轮询
下载失败 链接状态与有效期 过期、清理、网络 立即转存，单独重试下载

常见问题

429 是余额不足吗？

不一定。429 下可能是 1101 欠费、1102 资源包用尽，也可能是 1302 速率限制、1303 并发超限或 1304 IP 限制。先看业务码和 message，再决定充值、退避还是降并发。

任务失败会扣费吗？

取决于平台规则和失败原因。接入前确认失败、审核拒绝、超时取消分别如何计费，并以账单为准。不要假设失败一定不收费。

轮询多久一次合适？

从 5 秒起步，逐步退避到 15–30 秒，加随机抖动。设置总截止时间和最大次数，避免无限等待，也避免高频轮询给查询接口造成压力。

回调没收到怎么办？

先确认回调地址可公网访问、返回 HTTP 200、签名校验通过，再看时间戳是否在允许窗口内。文档没有承诺失败必重试，生产环境应保留轮询兜底。

结果链接打不开怎么办？

先看任务状态是否 succeeded、链接是否过期或结果是否已被清理。成功后应立即转存对象存储；链接失效后通常只能重新生成。

下一步

先在中商起航 AI 网关创建测试 Key，把 401、429、参数错误、任务失败和超时各演练一次，再接入生产监控。可用模型与计费方式以模型价格为准。

相关阅读：