Сбои Kling API делятся примерно на три уровня: уровень запроса (HTTP-статус и бизнес-код), уровень задачи (task failed) и уровень результата (ошибка скачивания). Порядок диагностики должен быть таким: сначала статус и бизнес-код, затем request_id и минимальное воспроизведение, и только потом изменение параметров или смена модели. Если идти в обратном порядке, легко принять проблему конфигурации за ограничение модели.

Ниже используются коды ошибок и статусы задач из документации открытой платформы Kling за октябрь 2026 года. Интерфейсы и коды могут меняться; приоритет — официальная документация.

Примечание: Kling и Kuaishou — товарные знаки Kuaishou и связанных с ней компаний. Статья носит технический характер и не означает аффилированности или одобрения. Коды, правила параллельности и биллинг определяются официальной документацией и страницей тарифов.

1. Сначала разделите три уровня сбоев

Сбой уровня запроса возвращается сразу: 401 — аутентификация, 400 — параметры, 403 — права, 429 — ограничение частоты или баланс, 5xx — ошибка сервера. Сбой уровня задачи происходит после успешной отправки и получения ID: статус становится failed, причина в поле message. Сбой уровня результата — задача уже succeeded, но ссылка не открывается, истекла или очищена.

Три уровня нужно фиксировать отдельно. Если считать сбой задачи ошибкой аутентификации и менять ключи, или считать ошибку скачивания сбоем генерации и повторять отправку, вы потеряете время и деньги.

2. 401: проверяем 1000–1004 по порядку

401 означает, что личность не подтверждена, и обычно не связан с возможностями модели или балансом. Бизнес-коды Kling: 1000 — ошибка аутентификации, 1001 — отсутствует поле Authorization, 1002 — недействительный токен, 1003 — токен ещё не действует, 1004 — токен истёк.

Текущие модели используют API Key в заголовке Authorization: Bearer; старый интерфейс применяет AK/SK и JWT с подписью HS256 и сроком около 30 минут. Смешивать способы нельзя. Проверяйте по порядку:

  1. Заголовок имеет вид Authorization: Bearer <учётные данные>, после Bearer есть пробел.
  2. В учётных данных нет пробелов, переводов строк и лишних кавычек — чат-окно особенно часто их приносит.
  3. Переменная окружения действительно загружена; можно вывести только префикс, но не полный ключ.
  4. Ключ не удалён, не ротирован и не отключён; JWT старого интерфейса не старше 30 минут, а часы машины не сдвинуты.
  5. Base URL, региональный домен и ключ относятся к одной платформе; не смешивайте зарубежный сервер и китайскую платформу.
  6. Обратный прокси не перезаписывает и не удаляет заголовок Authorization; секрет подписи callback настроен верно.
  7. Создайте новый ключ и выполните минимальный запрос, чтобы отделить проблему учётных данных от конфигурации прокси или шлюза.

3. 429, баланс и параллельность: сначала определите тип ограничения

429 не всегда означает «слишком быстро». В документации Kling 1100 — аномальный статус аккаунта, 1101 — задолженность по постоплате, 1102 — пакет исчерпан или просрочен; все три приходят под 429. 1302 — ограничение скорости, 1303 — превышение лимита параллельности пакета, 1304 — ограничение по белому списку IP; 1103 — это 403, отсутствие прав.

Параллельность считается по аккаунту, версии модели и типу пакета; все ключи одного аккаунта делят квоту. Задача занимает слот с submitted до успеха или ошибки; запросы статуса слот не занимают. Поэтому несколько ключей не обходят лимит параллельности.

Что делать: прочитайте message и бизнес-код, определите баланс, параллельность или права. Для 1302 и 1303 используйте экспоненциальную задержку с первым ожиданием не менее 1 секунды и очередь отправки. При постоянном превышении снизьте параллельность, разнесите нагрузку по времени или подберите пакет под фактический расход. Не устраивайте шторм повторов без задержки.

4. 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; превышена длина промпта.

Сначала воспроизведите ошибку минимальным запросом, затем добавляйте параметры по одному. Отказ модерации — не техническая поломка; не пытайтесь обходить его перебором ключевых слов.

5. Задача failed: статус, message и callback

Статусы задачи обычно submitted, processing, succeeded, failed; старый интерфейс может вернуть succeed вместо succeeded, поэтому слой совместимости должен поддерживать оба варианта. При failed смотрите message, request_id и параметры отправки.

Частые причины: не удалось скачать входное изображение или видео, модерация, ошибка рендеринга у поставщика, таймаут задачи, временная недоступность модели. Записи о сбоях сохраняйте, не удаляйте сразу — иначе нечего разбирать.

Если используется callback_url, проверяйте webhook-id, webhook-timestamp и webhook-signature; подпись — HMAC-SHA256. Тестовый callback допускается не чаще раза в 6 секунд, сервер должен вернуть HTTP 200. Документация не обещает повтор при неудачном callback, поэтому в production оставляйте опрос как резервный канал и не полагайтесь только на callback.

6. Таймауты и опрос: не превращайте асинхронную задачу в синхронную

Видеозадача может занимать от десятков секунд до нескольких минут, а в пиковые часы стоять в очереди. Таймаут соединения, таймаут чтения и общий таймаут задачи настраиваются отдельно: соединение можно ограничить коротко, чтение — по интерфейсу запроса, общий таймаут — по допустимому для бизнеса времени.

Рекомендуется начинать опрос с 5 секунд, постепенно увеличивать интервал до 15–30 секунд и добавлять случайный разброс. Задайте максимальное число попыток и общий дедлайн; после таймаута помечайте задачу как «требует проверки», а не ждите бесконечно. Коды 5000, 5001 и 5002 означают внутреннюю ошибку, временную недоступность сервиса и таймаут поставщика — их можно повторять с задержкой. 401, 403 и 1301 не следует повторять вслепую.

Ниже упрощённый пример на Python, объединяющий отправку, опрос, классификацию ошибок и скачивание:

import time
import random
import requests

API_KEY = "ваш-ключ-Kling"
BASE = "https://адрес-интерфейса-Kling"
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("Ошибка аутентификации: проверьте ключ, 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  # в production пишите потоком в объектное хранилище
        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, создана ли задача

7. Ошибка скачивания: срок ссылки и перекладывание

После успеха результат находится в outputs; у видео есть url, watermark_url и duration. Документация указывает, что результаты очищаются через 30 дней, а фактический срок ссылки может быть короче. Ошибки скачивания возникают из-за истечения ссылки, очистки результата, сетевого таймаута, прав объектного хранилища или блокировки прокси.

Рекомендации: сразу после успеха скачивайте и перекладывайте в собственное объектное хранилище; повторяйте скачивание и генерацию раздельно, не отправляйте задачу заново из-за ошибки загрузки; записывайте content-type, content-length и контрольную сумму; не публикуйте полную подписанную ссылку в открытых логах. Если результат уже очищен, обычно остаётся только генерировать заново, поэтому перекладывание должно быть первым шагом после callback или успешного опроса.

8. Повторы и идемпотентность: не платите дважды за один сбой

Перед повтором классифицируйте ошибку: 429, 5xx и сетевой таймаут можно повторять с задержкой; 400, 401, 403 и 1301 сначала нужно исправить, повторять их нельзя; при failed прочитайте message, устраните причину и только затем отправляйте новую задачу.

Kling поддерживает external_task_id и требует уникальности в рамках аккаунта. Передавайте номер бизнес-заказа или ключ идемпотентности; после сетевого таймаута сначала проверьте через external_task_ids, создана ли задача, и только потом решайте, повторять ли отправку. Иначе один «таймаут запроса» превратится в две задачи и двойное списание.

В таблице задач фиксируйте минимум: номер заказа, task_id, external_id, модель и параметры, статус, message, request_id, стоимость и число повторов. При сверке считайте уникальные task_id, а не количество отправок.

9. Таблица порядка диагностики

Симптом Что проверить сначала Частая причина Действие
401 Authorization, ключ, регион 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 секунд, добавьте случайный разброс. Задайте общий дедлайн и максимум попыток, чтобы не ждать бесконечно и не создавать нагрузку на интерфейс запроса.

Что делать, если callback не пришёл?

Проверьте доступность адреса из интернета, ответ HTTP 200 и прохождение проверки подписи, затем метку времени в допустимом окне. Документация не обещает повтор при ошибке, поэтому в production нужен резервный опрос.

Ссылка на результат не открывается. Почему?

Проверьте, что задача в статусе succeeded, не истекла ли ссылка и не очищен ли результат. После успеха сразу перекладывайте в объектное хранилище; после истечения ссылки обычно остаётся только повторная генерация.

Что дальше

Создайте тестовый ключ в ZSQH AI Gateway и по разу воспроизведите 401, 429, ошибку параметров, сбой задачи и таймаут, прежде чем подключать production-мониторинг. Доступные модели и правила биллинга — на странице тарифов.

Читайте также: