Los fallos de la API de Kling se dividen en tres capas: la capa de solicitud (código de estado HTTP y código de error de negocio), la capa de tarea (task failed) y la capa de resultado (fallo de descarga). El orden de diagnóstico debería ser: primero el código de estado y el código de negocio, después el request_id y la reproducción mínima, y solo al final cambiar parámetros o de modelo. Si se invierte el orden, es fácil confundir un problema de configuración con un problema de capacidad del modelo.

Este artículo toma como referencia los códigos de error y estados de tarea de la documentación de la plataforma abierta de Kling de octubre de 2026, y propone un orden de diagnóstico, reintentos e idempotencia. Las interfaces y los códigos pueden cambiar entre versiones, así que la referencia final es la documentación oficial.

Nota: Kling es una marca de Kuaishou y sus empresas vinculadas. Este artículo solo ofrece una explicación técnica y no implica afiliación ni respaldo alguno. Los códigos de error, las reglas de concurrencia y la facturación se rigen por la documentación oficial y la página de precios del sitio.

1. Distingue primero las tres capas de fallo

Los fallos de la capa de solicitud se devuelven de inmediato: 401 de autenticación, 400 de parámetros, 403 de permisos, 429 de límite de tasa o saldo, y 5xx de error del servidor. Los fallos de la capa de tarea ocurren después de enviar correctamente y obtener un ID: el estado pasa a failed y el motivo aparece en el campo message. Los fallos de la capa de resultado ocurren cuando la tarea ya está en succeeded pero el enlace de descarga no abre, expiró o fue eliminado.

Las tres capas deben registrarse por separado. Tratar un fallo de tarea como un fallo de autenticación y cambiar claves una y otra vez, o tomar un fallo de descarga como un fallo de generación y reenviar la tarea, hace perder tiempo y dinero.

2. 401 de autenticación: revisa de 1000 a 1004 uno por uno

Un 401 indica que la identidad no se validó y normalmente no tiene relación con la capacidad del modelo ni con el saldo. Los códigos de negocio que documenta Kling son: 1000 fallo de autenticación, 1001 falta el campo Authorization, 1002 token inválido, 1003 token aún no vigente y 1004 token expirado.

Los modelos actuales usan una clave de API en la cabecera Authorization: Bearer; las interfaces antiguas usan AK/SK para firmar un JWT con HS256 y una validez de unos 30 minutos. Ambos métodos no se pueden mezclar. Revisa en este orden:

  1. ¿La cabecera es Authorization: Bearer <credencial> y hay un espacio después de Bearer?
  2. ¿La credencial tiene espacios, saltos de línea o comillas extra antes o después? Copiar desde una ventana de chat es la causa más común.
  3. ¿Las variables de entorno se cargaron realmente? Puedes imprimir solo el prefijo para confirmarlo, sin mostrar la clave completa.
  4. ¿La clave fue eliminada, rotada o desactivada? En las interfaces antiguas, ¿el JWT superó los 30 minutos o el reloj de la máquina tiene desfase y aún no es válido?
  5. ¿La URL base, el dominio regional y la clave pertenecen a la misma plataforma? No mezcles direcciones de servidores internacionales con plataformas nacionales.
  6. ¿El proxy inverso sobrescribe o descarta la cabecera Authorization? ¿La clave de firma de callbacks está bien configurada?
  7. Haz una solicitud mínima con una clave nueva para distinguir si el problema es la credencial o la configuración del proxy o gateway.

3. 429, saldo y concurrencia: distingue primero el tipo de límite

No todos los 429 significan "solicitudes demasiado rápidas". En la documentación de Kling, 1100 indica estado de cuenta anómalo, 1101 pago pendiente en la modalidad de pospago y 1102 paquete de recursos prepagado agotado o vencido; los tres aparecen bajo 429. Además, 1302 es límite de velocidad, 1303 es concurrencia por encima del límite del paquete y 1304 es restricción por lista blanca de IP; 1103 corresponde a 403 sin permisos.

La concurrencia se calcula por cuenta, versión de modelo y tipo de paquete, y todas las claves de una misma cuenta comparten la cuota. Una tarea ocupa concurrencia desde que entra en submitted hasta que termina en éxito o fallo; las consultas no consumen concurrencia. Por eso, crear más claves no evita el límite de concurrencia.

Cómo proceder: lee primero message y el código de negocio para confirmar si es saldo, concurrencia o permisos; para 1302 y 1303 aplica retroceso exponencial con una espera inicial de al menos 1 segundo y coloca los envíos en una cola; si el límite persiste, reduce la concurrencia, distribuye la carga en horarios distintos o ajusta el paquete según el uso real. No lances una tormenta de reintentos sin retroceso contra el límite.

4. Errores 400/404 de parámetros y modelo: 1200 a 1203

1200 es un error genérico de parámetros, 1201 señala un campo o valor concreto, 1202 indica un método HTTP incorrecto y 1203 indica que el recurso o modelo no existe. 1300 significa que la solicitud entra en conflicto con la política de la plataforma, y 1301 que la entrada activó la política de seguridad de contenido; normalmente también son 400.

Las causas habituales incluyen: duración fuera del rango del modelo (2.5 Turbo solo admite 5 o 10 segundos, y la serie 3.0 va de 3 a 15 segundos); resolución no soportada (4K solo está disponible en algunos modelos); relación de aspecto, primer/último fotograma o número de imágenes de referencia incompatibles con el modelo; URL de imagen inaccesible para la plataforma; versión del modelo ausente en la ruta o en model_name; prompt por encima del límite de longitud.

Al diagnosticar, reproduce primero con la solicitud mínima y vuelve a añadir los parámetros uno por uno. Un rechazo de moderación de contenido no es una falla técnica; no intentes eludirlo cambiando palabras clave repetidamente.

5. Tarea failed: estado, message y callback

Los estados habituales de una tarea son submitted, processing, succeeded y failed; las interfaces antiguas pueden devolver succeed en lugar de succeeded, así que la capa de adaptación debe admitir ambos. Cuando el estado es failed, revisa message, request_id y los parámetros enviados.

Causas frecuentes: fallo al descargar la imagen o el video de entrada, moderación de contenido, error de renderizado upstream, tiempo de tarea agotado o modelo temporalmente no disponible. Las tareas fallidas deben conservar su registro; no las borres de inmediato o no podrás analizarlas después.

Si usas callback_url, valida webhook-id, webhook-timestamp y webhook-signature; la firma usa HMAC-SHA256. Las pruebas de callback admiten como máximo una cada 6 segundos, y el servidor debe responder HTTP 200 tras procesar correctamente. La documentación no promete reintentos ante fallos de callback, por lo que en producción conviene mantener el polling como respaldo y no depender solo del callback.

6. Timeouts y polling: no escribas una tarea asíncrona como si fuera síncrona

Las tareas de video suelen tardar entre decenas de segundos y varios minutos, y en horas pico se acumulan en cola. Configura por separado el timeout de conexión, el de lectura y el tiempo máximo total de la tarea: el de conexión puede ser corto, el de lectura se ajusta a la interfaz de consulta y el total según lo que el negocio pueda aceptar.

Para el polling, empieza con 5 segundos y aplica retroceso gradual hasta 15–30 segundos, con jitter aleatorio; define un número máximo de consultas y una fecha límite total, y al superarla marca la tarea como pendiente de confirmación en lugar de esperar indefinidamente. En los 5xx, los códigos 5000, 5001 y 5002 indican error interno, servicio temporalmente no disponible y timeout upstream respectivamente, y se pueden reintentar con retroceso; 401, 403 y 1301 no deben reintentarse a ciegas.

Este es un ejemplo simplificado en Python que encadena envío, polling, clasificación de errores y descarga:

import time
import random
import requests

API_KEY = "tu_credencial_de_kling"
BASE = "https://tu_endpoint_de_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/tu_ruta_de_modelo",
                         json=payload, headers=HEADERS, timeout=(5, 30))
    if resp.status_code == 401:
        raise RuntimeError("Fallo de autenticación: revisa la clave, Bearer y la región")
    if resp.status_code == 429:
        raise RuntimeError(f"Problema de límite, saldo o concurrencia: {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  # en producción, escribe en streaming al almacenamiento
        if status == "failed":
            raise RuntimeError(task.get("message") or "task failed")
        time.sleep(delay)
        delay = min(delay * 1.5, 30)
    raise TimeoutError(task_id)

# Antes de reenviar, consulta por external_task_ids si la tarea ya se creó

7. Fallo de descarga del resultado: vigencia del enlace y almacenamiento

Cuando la tarea termina bien, el resultado está en outputs, y el video incluye url, watermark_url y duration. La documentación indica que los resultados se eliminan a los 30 días y que el enlace puede tener una vigencia real más corta. Los fallos de descarga suelen deberse a enlace vencido, resultado eliminado, timeout de red, permisos del almacenamiento de objetos o bloqueo del proxy.

Recomendaciones: descarga y guarda el resultado en tu propio almacenamiento en cuanto termine; separa los reintentos de descarga de los de generación, de modo que un fallo de descarga no vuelva a enviar la tarea; registra content-type, content-length y un valor de verificación; no incluyas enlaces firmados completos en registros públicos. Si el resultado ya fue eliminado, normalmente solo queda regenerarlo, así que el almacenamiento debe ser el primer paso tras el callback o el polling exitoso.

8. Reintentos e idempotencia: no pagues dos veces por un fallo

Antes de reintentar, clasifica: los 429, los 5xx y los timeouts de red admiten retroceso y reintento; ante 400, 401, 403 y 1301 hay que corregir el problema primero y no reintentar; si la tarea está failed, revisa message, corrige la causa y envía una tarea nueva.

Kling admite external_task_id y exige que sea único dentro de una misma cuenta. Incluye el número de pedido o una clave de idempotencia al enviar; tras un timeout de red, consulta primero por external_task_ids para confirmar si la tarea ya se creó antes de decidir si la reenvías. De lo contrario, un "timeout de solicitud" puede convertirse en dos tareas y dos cargos.

La tabla de tareas debe registrar al menos: número de pedido, task_id, external_id, modelo y parámetros, estado, message, request_id, costo y número de reintentos. Al conciliar, deduplica por task_id y no cuentes por envíos.

9. Tabla de orden de diagnóstico

Síntoma Qué revisar primero Causa habitual Acción
401 Authorization, clave, región 1000–1004, JWT vencido o no vigente Corregir credencial, hacer solicitud mínima
429 Código de negocio y message 1101/1102 saldo, 1302 velocidad, 1303 concurrencia Recargar, retroceso, bajar concurrencia
400 Parámetros y contenido 1200/1201/1300/1301 Corregir según message; no eludir la moderación
404 Ruta, método, modelo 1202/1203 Ajustar ruta y nombre de modelo según la documentación
failed message, material de entrada Fallo de descarga, moderación, renderizado Corregir material o parámetros, conservar registro
Timeout Timeout de conexión/lectura/total Cola, tareas largas, 5xx upstream Configurar timeouts por capa, polling con retroceso
Fallo de descarga Estado y vigencia del enlace Vencimiento, eliminación, red Guardar de inmediato, reintentar solo la descarga

Preguntas frecuentes

¿Un 429 significa saldo insuficiente?

No necesariamente. Bajo 429 puede haber 1101 por pago pendiente, 1102 por paquete agotado, 1302 por límite de velocidad, 1303 por concurrencia excedida o 1304 por restricción de IP. Revisa primero el código de negocio y message para decidir si recargas, aplicas retroceso o reduces la concurrencia.

¿Se cobra una tarea fallida?

Depende de las reglas de la plataforma y del motivo del fallo. Antes de integrar, confirma cómo se facturan los fallos, los rechazos de moderación y las cancelaciones por timeout, y guíate por la factura. No supongas que un fallo nunca se cobra.

¿Cada cuánto conviene hacer polling?

Empieza con 5 segundos y aplica retroceso gradual hasta 15–30 segundos, con jitter aleatorio. Define una fecha límite total y un número máximo de consultas para evitar esperas infinitas y también para no saturar la interfaz de consulta con polling de alta frecuencia.

¿Qué hago si no llega el callback?

Confirma primero que la dirección de callback sea accesible desde internet, que responda HTTP 200 y que la validación de firma pase; después revisa si la marca de tiempo está dentro de la ventana permitida. La documentación no promete reintentos ante fallos, así que en producción conviene mantener el polling como respaldo.

¿Qué hago si el enlace del resultado no abre?

Revisa si el estado de la tarea es succeeded, si el enlace venció o si el resultado ya fue eliminado. Tras el éxito conviene guardar de inmediato en el almacenamiento de objetos; cuando el enlace caduca, normalmente solo queda regenerar.

Próximos pasos

Crea primero una clave de prueba en ZSQH AI Gateway y ensaya una vez cada caso: 401, 429, error de parámetros, tarea fallida y timeout; después conecta el monitoreo de producción. Los modelos disponibles y la facturación se rigen por precios de modelos.

Lecturas relacionadas: