Códigos de error de las API de texto a video explicados

La mayoría de los fallos de las API de texto a video se reducen a 5 grupos: solicitudes incorrectas, problemas de autenticación, límites de tasa, bloqueos de seguridad o problemas del servidor. Si reviso el estado HTTP, el cuerpo completo del error, el ID de la solicitud o tarea y la hora del fallo, normalmente encuentro la causa rápidamente.

Aquí está la versión corta:

• Los errores de la serie 400 normalmente significan que necesito corregir la solicitud.
• 401/403 suelen apuntar a la clave API, el acceso, la facturación o las reglas de IP.
• 429 significa que alcancé un límite de solicitudes, tareas o gasto.
• Un 200 OK al enviar no significa que el video terminó. Todavía necesito consultar la tarea y comprobar si hay failed.
• Los errores de la serie 500 suelen requerir un reintento, pero solo después de comprobar si la tarea sigue en ejecución.
• Los bloqueos de seguridad pueden ocurrir antes, durante o después de la generación, y algunas API pueden devolver menos clips en lugar de fallar toda la tarea.

Algunos números destacan. Las tareas de video, como las que usan Sora 2, pueden retener una GPU durante 30–90 segundos, los tiempos de espera del cliente pueden necesitar ser de más de 10 minutos, y un plan de reintentos común es empezar en 5 segundos, limitar a 60 segundos y detenerse tras 3 intentos.

Si quiero menos tareas fallidas y menos cargos duplicados, mantengo el flujo de trabajo simple:

• Registrar el cuerpo del error y el ID de la tarea
• Separar los errores de la capa API de los fallos a nivel de tarea
• Reintentar solo los casos 429 y 5xx
• Comprobar el estado de la tarea antes de volver a enviar la misma tarea
• Fijar versiones exactas del modelo en lugar de usar alias como latest

Mensajes de error de API para una BUENA experiencia de desarrollador

Comparación rápida

En resumen: el éxito del envío no es el éxito del renderizado. Trataría los resultados del sondeo como la fuente de verdad y usaría la carga útil del error, no solo el código de estado, para decidir qué hacer a continuación.

Errores de solicitud del lado del cliente: códigos de la serie 400 que puedes corregir

Después de registrar los detalles del error, el siguiente paso es averiguar qué salió mal en el lado de la solicitud. Empieza con el cuerpo del error y luego asigna el código HTTP a la solución.

400, 404, 413 y 415: qué significa cada código para las solicitudes de video

Cada código apunta a un tipo diferente de error en la solicitud. Un 400 normalmente significa JSON mal formado, campos requeridos faltantes o tipos de parámetros no válidos. Por ejemplo, pasar duration como una cadena ("6") en lugar de un entero (6) fallará la validación ^[4]. Un 404 significa que el ID del modelo o la ruta del endpoint es incorrecta, a menudo por un pequeño error tipográfico como wan2.7 en lugar de [wan-2.7](https://apimart.ai/ja/model/wan-2-7) o [wan-2.6](https://apimart.ai/model/wan-2-6) ^[7]. Un 413 aparece cuando una imagen o video de referencia es más grande que el límite de tamaño de carga ^[4][7]. Un 415 significa que el encabezado Content-Type es incorrecto, o que el modelo no admite el formato de archivo ^[5].

Incompatibilidades de modelo y parámetros que causan fallos de validación

Incluso cuando tu JSON está limpio, las solicitudes aún pueden fallar la validación porque no todos los modelos siguen las mismas reglas. La resolución, la duración, la relación de aspecto y los límites de recursos pueden cambiar de un modelo a otro.

Toma MiniMax-Hailuo-2.3. Admite 10 segundos a 768p, pero si solicitas 1080p, la duración máxima baja a 6 segundos ^[6]. Las reglas de recursos pueden ser igual de estrictas. Kling 3.0 requiere que las imágenes de entrada tengan al menos 300 px en ambas dimensiones, con una relación de aspecto entre 1:2.5 y 2.5:1. Wan 2.7 requiere que los videos de referencia duren entre 2 y 10 segundos y no superen los 100 MB ^[4][7].

Un 422 normalmente significa que tus parámetros entran en conflicto entre sí. Por ejemplo, SkyReels V4 devuelve 422 cuando combinas campos de Image-to-Video y Omni en la misma solicitud ^[8].

Un pequeño hábito puede ahorrar mucho tiempo: usa cadenas de versión fijadas en lugar de alias genéricos. Las reglas de parámetros pueden cambiar entre versiones de modelo ^[3]. Si la validación sigue fallando, comprueba los límites exactos del modelo antes de reintentar.

Si la solicitud valida pero aún falla, pasa a la autenticación, los límites de tasa y las comprobaciones de seguridad.

Autenticación, permisos y límites de tasa

Una vez que pasa la validación, la mayoría de los fallos restantes se reducen a tres cosas: autenticación, permisos o límites de tasa.

401 y 403: errores de clave API y de acceso

Un error 401 Unauthorized significa que la solicitud no incluyó credenciales de autenticación válidas. Las causas habituales son una clave API faltante, una clave no válida, una clave que se deshabilitó o eliminó, o un encabezado Authorization roto ^[9][1][2].

Muchas API esperan:

Authorization: Bearer YOUR_API_KEY

Algunas plataformas usan x-api-key en su lugar. Así que si el nombre o el formato del encabezado está mal, eso por sí solo puede desencadenar un 401 ^[1][10].

Empieza por lo básico. Comprueba la variable de entorno, asegúrate de que la clave siga activa y confirma que tu configuración de CI/CD inyecta los secretos correctamente en cada entorno ^[3]. También ayuda leer el cuerpo de la respuesta en lugar de detenerse en el código de estado HTTP. Errores como invalid_api_key, token_expired o account_banned normalmente te dicen qué se rompió mucho más rápido ^[9][3].

Un 403 Forbidden significa que el servidor te reconoció, pero aun así bloqueó la solicitud. Eso normalmente apunta a un problema de acceso. Puede que tu clave no tenga el alcance de modelo correcto, que tu plan de cuenta no incluya ese endpoint, que tus créditos se hayan agotado o que la IP de tu solicitud no esté en la lista de permitidos ^[3][9].

El cuerpo de la respuesta también importa aquí. Si ves insufficient_credits, revisa la facturación. Si ves permission_error, comprueba los alcances, el acceso al modelo o los límites del plan. Y si el acceso parece correcto pero el tráfico es demasiado alto, la siguiente parada suele ser 429.

429: errores de límite de tasa y cuota excedida

Si la autenticación tiene éxito, el volumen de solicitudes suele ser el siguiente cuello de botella. Un error 429 Too Many Requests significa que alcanzaste una limitación, un límite de concurrencia o un límite de gasto ^[3][9][10]. En pocas palabras: enviaste demasiadas solicitudes en una ventana corta, ejecutaste demasiadas tareas a la vez o cruzaste un límite de facturación ^[3][9].

De nuevo, el cuerpo de la respuesta te da la mejor pista. rate_limit_exceeded normalmente significa que deberías usar backoff exponencial. spend_limit_exceeded significa que es hora de revisar la configuración de facturación ^[3][9].

Pon en cola las tareas por lotes localmente cuando puedas, y vigila estos encabezados ^[2]:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset

Si usas APIMart, una sola clave para todos los modelos puede reducir la deriva de autenticación ^[3]. Aun así, el flujo de depuración sigue siendo prácticamente el mismo: lee el cuerpo de la respuesta, verifica tus variables de entorno y asegúrate de que la cuenta pueda acceder al modelo que estás llamando.

Bloqueos de seguridad, tiempos de espera y fallos del lado del servidor

Después de que pasen la validación de la solicitud y la autenticación, los fallos que quedan suelen caer en dos grupos: bloqueos de moderación y problemas del lado del servidor. Así que una vez despejados la autenticación, la cuota y la validación, divide el resto de tu depuración en esas dos rutas.

Errores de moderación y de política de contenido en la generación de video

Los bloqueos de seguridad pueden ocurrir en tres momentos distintos: antes de que empiece la generación (la solicitud se rechaza de inmediato), durante el renderizado (la tarea se detiene a medio camino) o después de que se produzca el video (la salida se filtra antes de la entrega) ^[11]. Ese último caso confunde a la gente. Una tarea puede terminar y aun así no entregar nada si el resultado se filtra.

Con las API basadas en sondeo, el estado HTTP puede ser engañoso. Podrías obtener 200 OK de la comprobación de estado, mientras que el cuerpo JSON dice state: "failed" e incluye un error como SensitiveContentDetected o NSFW ^[12]. En la práctica, el cuerpo del sondeo es la fuente de verdad, no el código de estado HTTP.

Si se activa un bloqueo de moderación, no reintentes exactamente el mismo prompt. Reescríbelo. Una redacción cinematográfica sencilla y técnica puede ayudar a reducir los falsos positivos de los filtros de seguridad estrictos ^[11]. Por ejemplo:

• gimbal shot
• medium tracking shot
• golden hour lighting

Hay otro detalle aquí. Algunos modelos, incluido Google Veo, pueden devolver menos clips de los que pediste cuando algunas salidas son bloqueadas por los filtros de seguridad, en lugar de fallar toda la tarea ^[3]. Así que no te limites a comprobar si la solicitud se completó. Comprueba que el número de recursos devueltos coincida con el número que solicitaste.

Si el prompt parece limpio y la tarea sigue fallando, pasa a la siguiente capa: la estabilidad del servidor.

Errores 500, 502, 503 y de tiempo de espera en tareas de video asíncronas

Los fallos del lado del servidor están en una parte diferente del flujo de depuración. Las tareas de texto a video a menudo retienen una ranura de GPU durante 30–90 segundos ^[3], lo que las hace más sensibles a la sobrecarga y a los tiempos de espera.

Para los errores 500 y 504, comprueba el estado de la tarea antes de reintentar. Los reintentos a ciegas pueden crear renderizados duplicados y duplicar tus costos ^[3]. Registra cada taskId o prediction_id para poder consultar el endpoint de estado directamente antes de enviar una nueva tarea ^[3][13].

Cuando los reintentos son seguros, usa backoff exponencial con jitter. Una configuración práctica es:

• empezar en 5 segundos
• limitar a 60 segundos
• detenerse tras 3 intentos ^[13][12]

Configura los tiempos de espera del cliente en 10 minutos o más ^[3], y activa alertas ante valores crecientes de predict_time ^[3].

Un flujo de trabajo de depuración paso a paso para las API de texto a video

Clasifica el error y luego aplica la solución correcta

Usa este flujo de trabajo para ir del síntoma a la solución en una sola pasada. Primero, lee el cuerpo completo de la respuesta. Luego clasifica el fallo según el código de estado HTTP y lo que dice el cuerpo del error. Algunos proveedores también envían rangos de errores internos, pero tu guía principal debe ser el código de estado HTTP y el cuerpo del error ^[3][1].

Empieza con el cuerpo de la respuesta y luego coloca el resultado en uno de estos grupos:

Una vez que se ha enviado una tarea, deja de pensar solo en términos de respuestas HTTP y mira también el estado de la tarea. Para las tareas asíncronas, comprueba la respuesta del sondeo en busca de failed o expired antes de volver a enviar la misma tarea. Ese solo paso puede ahorrarte costos adicionales y mucha confusión.

Antes de tocar el código, comprueba la página de estado del proveedor. Si el servicio está degradado, la depuración local no te dirá mucho. Después de eso, inspecciona los encabezados de respuesta x-deny-reason. Las denegaciones a nivel de proxy pueden parecer errores del modelo si te saltas esa comprobación ^[3].

Además, fija cadenas exactas de versión del modelo como kling-v3.0-std en lugar de latest. Una actualización silenciosa del modelo puede introducir nuevos fallos de validación en un pipeline que funcionaba bien el día anterior ^[3].

Conclusiones clave para integraciones más fiables

La mayoría de los fallos de las API de texto a video siguen unos pocos patrones repetibles. Si obtienes un error 4xx, necesitas cambiar la solicitud, las credenciales o la configuración. Enviar la misma llamada de nuevo normalmente no arreglará nada.

• Registra las entradas de la solicitud: ID del modelo, hash del prompt y parámetros (consulta nuestros tutoriales de API de IA para conocer las mejores prácticas de registro).
• Registra el ID de la tarea, el estado final, predict_time y el mensaje de error completo.
• Reintenta solo 429 y 5xx tras comprobar el estado de la tarea para evitar renderizados duplicados y costos duplicados ^[3].
• Vigila los picos en predict_time: pueden señalar de forma temprana una degradación de la infraestructura ^[3].

Preguntas frecuentes

¿Cómo sé si una tarea de video realmente falló?

Sondea el endpoint de estado de la tarea con el ID de la tarea que obtuviste al enviarla. Si el campo status regresa como failed, la tarea no se completó.

A continuación, mira el campo error en la respuesta. Eso te dice por qué falló, para que puedas decidir qué hacer a continuación:

• ajustar tu prompt
• comprobar el saldo de tu cuenta
• esperar si hay un problema de infraestructura

También puedes usar webhooks para recibir notificaciones automáticas cuando una tarea entra en estado de fallo.

¿Cuándo debo reintentar una solicitud a una API de texto a video?

Reintenta los errores transitorios como los límites de tasa 429 y los problemas del lado del servidor 500 con backoff exponencial. Eso ralentiza los intentos repetidos y te ayuda a evitar sobrecargar el sistema.

Para un 504 Gateway Timeout o un fallo de tarea, comprueba el estado de la tarea antes de volver a intentarlo. Un reintento a ciegas puede desencadenar renderizados duplicados y añadir costos adicionales.

No reintentes los errores 400 o 401. Esos normalmente significan que la propia solicitud necesita corregirse primero.

¿Por qué se bloquearía un prompt después del envío?

Un prompt normalmente se bloquea porque choca con las reglas de seguridad o moderación de un proveedor. Eso puede ocurrir justo cuando lo envías, o más tarde durante la generación si el sistema detecta contenido visual o de audio prohibido.

Los desencadenantes comunes incluyen temas sensibles, violencia, menores o material protegido por derechos de autor. Y como los sistemas de moderación tienden a ser cautelosos, incluso los prompts inofensivos pueden marcarse.

Si eso ocurre, reescribe la solicitud en un lenguaje más neutral y descriptivo.