· reAPI Team
Estado de la API de fal: COMPLETED, pero sin resultado
Entiende el estado de la API de fal cuando COMPLETED no devuelve ningún resultado. Revisa respuestas, errores, campos de salida y webhooks antes de reintentar una generación.

COMPLETED es un mal punto para dejar de leer. En la API de colas de fal, significa que la solicitud ha terminado, incluidas las que fallaron o se cancelaron. No indica que se haya producido una imagen o un vídeo utilizable.[1]
La siguiente llamada debe ir al endpoint de resultados de la solicitud original. Esa respuesta contiene el estado HTTP y el cuerpo del modelo.[2] Si tu aplicación ha puesto el indicador de progreso en verde pero no encuentra un archivo, sigue ese resultado antes de enviar otra generación. Puede que te falte un paso de recuperación, que estés leyendo el objeto JSON equivocado o que estés ante un error real del modelo.
El estado indica cuándo recuperar el resultado
El estado de la cola de fal pasa por IN_QUEUE, IN_PROGRESS y COMPLETED. Cuando llegue a COMPLETED, lee el resultado. Campos como metrics.inference_time y cualquier información de error disponible aportan contexto útil, pero no sustituyen la respuesta del modelo.[1]
Esta separación aparece en los propios ejemplos de la API de fal: envía la solicitud, consulta su estado, recupera su resultado y revisa el Output Schema del modelo. fal.queue.status() y fal.queue.result() del cliente JavaScript realizan operaciones distintas. En Python, después del estado completado se llama a handler.get().[3][4]
Mira la variable que tu aplicación pasa al componente de imagen. Si contiene el estado de la cola, todavía no has llegado al objeto que necesita el componente. Recupera primero el resultado. Si contiene el objeto envolvente del resultado del SDK de JavaScript, lee su propiedad data antes de aplicar el esquema de salida del modelo.[3] Cambiar images por image por ensayo y error es menos útil que comprobar qué respuesta tienes realmente.
Aquí importa el método de llamada. subscribe() envía y espera en la cola por ti, mientras que submit() devuelve el control para que tu aplicación gestione el ciclo de vida. La llamada directa run() no utiliza la cola.[4] Por tanto, un ejemplo escrito para un método puede incluir un paso de espera o de extracción que tu código aún necesita, o uno que ya ha realizado.
Usa las URL devueltas por el envío original
Guarda request_id, status_url y response_url cuando el envío tenga éxito. La guía de colas de fal recomienda usar las URL devueltas. Si construyes tú las URL de consulta, la guía distingue entre la ruta owner/app y la ruta completa del endpoint del modelo que se usa para enviar el trabajo.[3] Añadir todos los sufijos del modelo a una ruta de estado de solicitud puede dirigir la consulta al lugar equivocado.
Para un worker que pueda reiniciarse, guarda esos valores fuera del proceso antes de esperar. Así, tu tarea local podrá continuar leyendo la misma solicitud. Es una recomendación de diseño de aplicaciones: un botón de reintento no debería tener que reconstruir el envío original solo para averiguar si existe su resultado.
El siguiente JavaScript lee una solicitud guardada en tu servidor. Las URL deben proceder de la respuesta de envío de fal fiable de ese servidor, no de entradas arbitrarias del navegador: la solicitud adjunta tu credencial de API.
async function inspectFalRequest(saved, key) {
async function read(url) {
const response = await fetch(url, {
headers: { Authorization: `Key ${key}` },
redirect: "error",
});
const raw = await response.text();
let body;
try {
body = JSON.parse(raw);
} catch {
body = raw;
}
return { http: response.status, ok: response.ok, body };
}
const state = await read(saved.status_url);
const lifecycle = state.body?.status;
if (!state.ok || !["IN_QUEUE", "IN_PROGRESS", "COMPLETED"].includes(lifecycle)) {
return { stage: "status-read-error", ...state };
}
if (lifecycle !== "COMPLETED") {
return { stage: "pending", ...state };
}
const result = await read(saved.response_url);
return { stage: "result", ...result };
}Esta función auxiliar conserva deliberadamente como texto una respuesta que no sea JSON. De lo contrario, un fallo al analizar el JSON podría sustituir el error útil por otra excepción. Un fallo de conexión sigue lanzando una excepción al código que llama; conserva la solicitud guardada para que el siguiente paso de recuperación pueda inspeccionar la misma tarea. La función no hace ningún POST de generación.
Su indicador ok es el resultado HTTP de la lectura, no una afirmación de que tu producto tenga un recurso utilizable. Todavía debes inspeccionar el cuerpo. Del mismo modo, status-read-error significa que esta consulta no logró determinar el estado de la cola. No significa que la generación remota haya fallado.
En Python, inspecciona tanto la gestión de excepciones alrededor de handler.get() como la propia llamada. Un manejador general que devuelve None para cada excepción deja a la siguiente parte de tu aplicación con un valor vacío y sin explicación. Conserva la información de la excepción para el diagnóstico y proporciona a la aplicación una ruta de error diferenciada. No dejes que el mismo valor vacío represente una solicitud aún pendiente, una entrada rechazada y un archivo generado correctamente que todavía no se ha descargado.
Durante la depuración de JavaScript, un registro de los nombres de campo de la respuesta del que se hayan eliminado los datos sensibles puede revelar una ruta de objeto errónea. Mantén las credenciales y el contenido privado de entrada fuera de los registros compartidos. Una vez establecida la ruta, valida los campos obligatorios antes de pasar el resultado al componente de imagen o vídeo.
Si el problema es la autenticación, comprueba la cuenta que creó la tarea. Las claves de fal se crean en el área Keys del panel y pertenecen a la cuenta seleccionada. Mantén la credencial en tu servidor, normalmente en FAL_KEY; las solicitudes directas usan Authorization: Key ....[5] Crear una clave en otra cuenta no trasladará una solicitud existente a esa cuenta. No pongas una clave válida en el código del navegador para facilitar la depuración.
Lee el fallo donde se produjo
Una respuesta de resultado puede explicar por qué una solicitud completada no tiene contenido multimedia. fal documenta los siguientes estados de resultado:[2]
| Respuesta de resultado | Qué inspeccionar |
|---|---|
400, solicitud aún en curso | Vuelve a la URL de estado guardada y sigue observando esa solicitud |
401 | La credencial, la cabecera y la cuenta usadas para la consulta |
404 | El ID de solicitud, la URL de consulta, la cuenta y las reglas de conservación aplicables |
422 | El error de validación o del modelo devuelto |
499 | La cancelación registrada |
500 u otro error del servidor | El cuerpo real de la respuesta y el ID de solicitud |
No reduzcas la última fila a un tiempo de espera de conexión agotado. Recibir un error del modelo desde el endpoint de resultados te da una respuesta que inspeccionar. No lograr llegar al endpoint te deja sin esa respuesta. Las decisiones de recuperación son distintas.
Por ejemplo, no_media_generated es un error de modelo 422 documentado: la generación terminó sin producir el contenido multimedia esperado. fal lo marca como no reintentable.[6] Es un diagnóstico concreto cuando el error devuelto lo indica. Un componente de imagen vacío no basta para asignar ese diagnóstico por tu cuenta.
Conserva intacta la estructura del error. Los errores de solicitud pueden tener una cadena detail y un error_type; los errores de validación del modelo pueden contener un array detail con entradas tipadas. fal también señala que algunos endpoints no han adoptado el formato de error de modelo más reciente.[6][7] Un analizador que espere una única estructura para todos los errores puede ocultar el mensaje que más necesitas.
Cuando el resultado indique un error de archivo de entrada, inspecciona también el archivo de origen. Una URL que funciona en tu navegador con la sesión iniciada puede no ser recuperable públicamente por el servicio. La guía de archivos de fal exige URL de entrada accesibles y señala que los servidores de alojamiento pueden bloquear las solicitudes o limitar su frecuencia.[8] Comprueba esa condición antes de cambiar el analizador de salida; un fallo al recuperar la entrada y un error de campo de salida ocurren en etapas distintas.
Por tanto, «La llamada a la API falló» en una aplicación es un punto de partida para investigar, no la explicación. Registra qué llamada falló y conserva su estado y cuerpo. Si estás decidiendo si el fallo debería haber costado créditos, usa la guía de facturación de solicitudes fallidas después de identificar el resultado real de la solicitud.
Una respuesta JSON correcta aún requiere comprobar el contenido multimedia
Abre el Output Schema del endpoint exacto al que enviaste la solicitud. Determinados modelos de imagen devuelven un array images, mientras que otros modelos usan otras estructuras. Algunos exponen sync_mode, que puede devolver el contenido multimedia como data URI y omitir la salida del historial de solicitudes.[8] Son detalles específicos de cada modelo. Un manejador genérico que suponga que cada resultado contiene un video.url descargable no los cubrirá.
Supongamos, en cambio, que la respuesta del modelo contiene la URL de salida esperada, pero falla la subida a tu almacenamiento. Es un caso hipotético de recuperación. Conserva la URL y el ID de solicitud original, reintenta el paso de transferencia mientras el archivo siga disponible y verifica que se puedan leer los bytes guardados. Volver a ejecutar la generación produciría una operación nueva sin explicar qué ocurrió con el archivo original.
Aquí también es donde una migración de API necesita una correspondencia explícita de campos. Las tareas multimedia ordinarias de reAPI devuelven su estado de negocio y sus arrays multimedia en una misma respuesta de tarea, con output.image_urls o output.video_urls. La referencia de tareas y la referencia de errores distinguen entre un resultado multimedia ausente y un fallo al guardar el archivo generado.[9][10] Incluso ahí, un HTTP 200 no basta: lee el estado de la tarea y valida lo que necesita tu aplicación. Cambiar de proveedor no elimina el paso de gestión de archivos.
Los webhooks añaden otro objeto que debes distinguir
Los estados de los webhooks de fal usan OK y ERROR, en lugar de los valores del ciclo de vida de la cola. Una notificación OK puede tener payload: null y payload_error cuando el resultado no se puede representar como JSON. Su documentación te remite al resultado de la cola para recuperarlo.[11]
Si tu flujo de trabajo está controlado por webhooks, inspecciona toda la notificación antes de decidir que no hay resultado. Un analizador escrito para el campo status de la cola no debería reutilizarse sin cambios para el estado y la carga útil del webhook. Asocia la notificación con la solicitud existente y luego recupera el resultado si eso es lo que indican sus campos.
Para tareas largas, fal recomienda el estado de la cola y los webhooks en vez de mantener abierta indefinidamente una llamada bloqueante.[3] Conserva una ruta de consulta en tu propio flujo de trabajo incluso cuando los callbacks sean la vía normal. Una notificación perdida debería dejarte un ID que investigar, no obligarte a generar de nuevo para poner el flujo en marcha.
Guarda pronto los resultados completados. La disponibilidad del resultado de la cola, el almacenamiento de cargas útiles en el historial de solicitudes y la conservación de archivos multimedia son cuestiones separadas; el tamaño del resultado y los ajustes de almacenamiento pueden afectarlas de forma diferente.[2][11][12] Si necesitas el archivo más adelante, cópialo a un almacenamiento que controles y registra si la copia se realizó correctamente. Una URL guardada por sí sola no es un archivo de conservación.
Cuándo comprobar si hay una interrupción del servicio
Si no puedes recuperar el resultado original, compara la hora del fallo y el servicio afectado con la página oficial de estado y el historial de incidentes de fal. Esa página separa los componentes, así que mira la parte pertinente para tu solicitud en lugar de tratar cualquier aviso como explicación de todos los errores.[13] Este artículo no ofrece una evaluación de disponibilidad en tiempo real.
Un estado completado sin ningún archivo visible no establece por sí solo que fal esté caído. Tampoco la ausencia de un aviso de estado demuestra que tu código esté mal. La siguiente evidencia útil sigue siendo la respuesta de resultado original: su código HTTP, cuerpo, endpoint e ID de solicitud. Cuando la tengas, podrás decidir si debes corregir la recuperación, corregir una entrada, recuperar un archivo o escalar un error de servicio sin resolver.
Referencias
- fal. Obtener el estado de una solicitud. Referencia de la API de colas. Consultado el 15 de noviembre de 2026.
- fal. Obtener el resultado de una solicitud. Referencia de la API de colas. Consultado el 15 de noviembre de 2026.
- fal. Cola. Guía de inferencia de las API de modelos. Consultado el 15 de noviembre de 2026.
- fal. Métodos de inferencia: cómo llamar a los modelos de fal. Consultado el 15 de noviembre de 2026.
- fal. Obtener tu clave de API. Consultado el 15 de noviembre de 2026.
- fal. Errores del modelo. Incluye la entrada
no_media_generated. Consultado el 15 de noviembre de 2026. - fal. Errores de solicitud. Guía de las API de modelos. Consultado el 15 de noviembre de 2026.
- fal. FLUX.1 [dev] API. Secciones Files y Schema. Consultado el 15 de noviembre de 2026.
- reAPI. Tareas. reapi.ai/docs/api/tasks. Consultado el 15 de noviembre de 2026.
- reAPI. Errores. reapi.ai/docs/api/errors. Consultado el 15 de noviembre de 2026.
- fal. Webhooks. Guía de inferencia de las API de modelos. Consultado el 15 de noviembre de 2026.
- fal. Conservación de datos. Guía de las API de modelos. Consultado el 15 de noviembre de 2026.
- fal. Estado de fal. Interfaz de la página oficial de estado comprobada el 15 de noviembre de 2026; aquí no se afirma ninguna evaluación de disponibilidad.