Solución de problemas

Busca el síntoma y prueba la solución. Si nada de esto ayuda, contacta con soporte con el request_id.

Falla la primera llamada

401 «Missing credentials». No llegó la cabecera Authorization. Comprueba que la variable de entorno está definida en la shell o el proceso que ejecuta la solicitud (echo ${POPNOW_API_KEY:0:10} debería mostrar sk-popnow-) y que ningún proxy ni librería HTTP está quitando la cabecera.

401 «Key format is not recognized». El valor no es una clave de PopNow; a menudo es otra cosa que había en el portapapeles. Las claves empiezan por sk-popnow-.

401 «Credentials are invalid or expired». La clave se revocó, caducó o está mal escrita. Crea una nueva en la consola de la API.

40310. El correo de tu cuenta no está verificado. Abre el enlace del correo de registro; la clave funciona justo después.

40201 «Insufficient balance». La cuenta no tiene créditos suficientes para la retención de esta tarea. Las retenciones de video pueden ser grandes; mira el precio con jobs/quote y compra créditos.

Se rechaza la solicitud

400 que nombra un campo. El input no coincide con el esquema del modelo: un campo mal escrito, un valor fuera de la lista permitida o un campo obligatorio que falta. Abre la página de referencia del modelo desde Modelos y compara.

400 «Invalid callback URL». El callBackUrl tiene que ser HTTPS público, en el puerto 443, sin usuario ni contraseña. Se rechazan localhost y las direcciones privadas.

40004. El modelo funciona, pero ahora no puede atender esa combinación de ajustes. Cambia el ajuste que nombra msg (a menudo la resolución, la duración o la relación de aspecto).

50301. El modelo no puede aceptar tareas por un tiempo. Inténtalo más tarde o elige otro modelo.

413. El cuerpo JSON pasa de 2 MiB, normalmente por imágenes incrustadas. Súbelas en su lugar.

Falla la tarea

invalid_asset. No se pudo descargar o leer un archivo de referencia. Abre la URL en una ventana privada del navegador: tiene que descargar el archivo en sí, sin iniciar sesión. Las páginas para compartir de las nubes no funcionan.

content_rejected. El modelo rechazó el prompt o una imagen de referencia. Reformúlalo, usa otras referencias o prueba otro modelo.

timeout o expired. El trabajo tardó más de lo permitido. Prueba con menos duración o menos resolución.

generation_failed. El modelo se ejecutó pero no produjo nada. La misma entrada suele volver a fallar; cambia el prompt o los ajustes.

Las tareas fallidas y caducadas no gastan créditos.

El resultado

El enlace de descarga devuelve 403 o «expired». Los enlaces firmados duran unos 20 minutos. Vuelve a leer la tarea con recordInfo para conseguir uno nuevo.

El enlace de descarga falla cuando envío mi clave de API. No envíes Authorization al enlace firmado; el enlace en sí es el permiso.

recordInfo devuelve 404 para una tarea que creé. Las tareas solo las ve la clave que las creó. Usa la misma clave o búscala en la consola de la API.

Webhooks

No llega nada. Comprueba que la URL es accesible desde internet por HTTPS, que tu firewall la permite y que tu manejador responde 2xx en menos de 15 segundos. Las entregas fallidas aparecen en la consola de la API.

La firma nunca coincide. Calcula el hash de los bytes en bruto del cuerpo, no de un JSON reserializado; usa data.taskId, la cabecera X-Webhook-Timestamp y el secreto que generaste más recientemente.

La misma tarea llega dos veces. Es lo esperado tras un reintento. Ignora los duplicados por request_id.

Subidas

El PUT devuelve 403 desde el almacenamiento. Hay una cabecera distinta a la del ticket. Envía Content-Type y Content-Length exactamente como vienen y sin cabecera Authorization.

La confirmación devuelve 40003. El archivo subido no coincide con lo que declaraste. Pide un ticket nuevo con el contentType y los bytes correctos.

La confirmación devuelve 409. El ticket caducó (a los 20 minutos más o menos). Pídelo justo antes de subir.