Quien busca «errores de la API de Midjourney» normalmente no encuentra una tabla oficial de códigos. Midjourney no tiene una API general para el público: lo que se llama así suele ser un encapsulamiento de terceros o una pasarela de relay, y los códigos de estado, los campos de error y las reglas de reintento los define el proveedor. Un mismo 401 puede tener causas distintas en dos plataformas.
Este artículo clasifica fallos comunes por semántica HTTP y ciclo de vida de la tarea, y ofrece orden de diagnóstico, reintentos con idempotencia y una lista para abrir tickets. Las interfaces, los códigos y la facturación se rigen por la documentación del proveedor.
Aviso de marcas: Midjourney es una marca de Midjourney, Inc.; Discord es una marca de Discord Inc. Los encapsulamientos y servicios de relay de terceros que se tratan aquí no tienen relación de afiliación con esas empresas; las interfaces, los códigos de error y la facturación se rigen por la documentación del proveedor.
1. Primero, ubica en qué capa ocurre el error
Una llamada atraviesa cinco capas: cliente y red, autenticación de la pasarela, grupo de cuentas upstream, tarea de generación y almacenamiento de resultados y CDN. Cada capa falla de forma distinta:
| Síntoma | Capa probable | Primer paso |
|---|---|---|
| Fallan todas las interfaces | Cliente, red, DNS, proxy | Cambiar de red o reproducir con una petición mínima |
| Solo falla Midjourney | Canal o grupo de cuentas upstream | Revisar la página de estado y otros modelos |
| 4xx en la fase de envío | Autenticación, parámetros, límite de tasa | Revisar la solicitud contra el código de error |
| Envío correcto pero tarea fallida | Generación, moderación, cuenta upstream | Leer el campo de error de la tarea |
| Tarea correcta pero la imagen no abre | Enlace de resultado, CDN, descarga | Verificar la vigencia del enlace y reintentar la descarga |
Antes de diagnosticar, responde tres preguntas: ¿falla todo o solo algunos casos? ¿Falla el envío o la tarea? ¿Se reproduce siempre o solo en horas pico? Esas tres respuestas reducen el alcance a la mitad.
2. 401 y 403: autenticación, permisos y estado de cuenta
El 401 indica que la identidad no fue reconocida. Las causas habituales son: encabezado ausente o mal escrito, clave con espacios sobrantes o ya rotada, uso de una cookie web o un token temporal como clave de API, URL base incorrecta, o desfase del reloj del sistema que invalida la firma.
El 403 indica que la identidad fue reconocida pero no tiene acceso. Las causas habituales son: la clave no tiene habilitado el modelo, la IP no está en la lista permitida, la región está restringida, el plan venció, la cuenta quedó marcada por control de riesgo o los permisos del espacio de trabajo son insuficientes.
Orden de tratamiento:
- Reproduce con una petición mínima, conservando solo el encabezado de autenticación y los parámetros obligatorios.
- Compara con la documentación el nombre y el prefijo del encabezado; revisa si hay un espacio después de Bearer.
- En la consola, confirma el estado de la clave, los permisos de modelo, el saldo y la fecha de vencimiento.
- Prueba con una clave de prueba nueva; si sigue el 403, consulta al proveedor por la IP, la región y el estado del grupo de cuentas.
No pongas la clave en el código del frontend ni en repositorios públicos. Ante un 401, sospecha primero de la configuración y no reintentes en cadena: reintentar no convierte una clave incorrecta en correcta.
3. 429: límites de tasa, concurrencia y cuota
El significado del 429 es más amplio de lo que muchos suponen. Puede indicar que se superó el número de solicitudes por minuto, el número de tareas concurrentes, la cuota diaria, que el grupo de cuentas no tiene cuentas disponibles por el momento, o que el upstream está en cola. Cada causa se trata de forma distinta.
Revisa primero los encabezados y el cuerpo del error: si hay Retry-After, espera ese tiempo; si el mensaje menciona quota o balance, suele ser un problema de cuota; si menciona concurrency o queue, suele ser concurrencia; si todas las claves reciben 429 al mismo tiempo, puede que el grupo de cuentas del proveedor esté saturado.
Formas de responder:
- Añade una cola en el cliente y limita la concurrencia; no satures de golpe.
- Usa backoff exponencial con jitter para evitar que todos reintenten en el mismo instante.
- Distingue «esperar un poco y se recupera» de «hay que recargar o ampliar la cuota».
- Registra el modelo, la franja horaria y el volumen de solicitudes de los 429 para saber si es tu tráfico o la capacidad upstream.
El 429 no se resuelve probando más veces; los reintentos ciegos alargan la cola y pueden prolongar el bloqueo.
4. Prompt rechazado: moderación y errores de parámetros
Un «prompt rechazado» tiene dos tipos de causa. La primera es la moderación de contenido: violencia, contenido sexual, menores, celebridades reales, personajes protegidos por derechos de autor, marcas, figuras políticas y otros elementos pueden activarla. La segunda es un error de parámetros: relación de aspecto no admitida, versión de modelo inexistente, prompt demasiado largo, URL de imagen de referencia inaccesible o formato no admitido.
Ninguno de los dos casos debe reintentarse tal cual. Ante un rechazo de moderación, ajusta el material y la formulación; no uses sinónimos, separación de caracteres ni descripciones veladas para eludirla una y otra vez. Ante un error de parámetros, corrige los campos según la documentación. Registra el prompt rechazado, la versión del modelo y el cuerpo de la respuesta, y conviértelos en una lista negra y reglas de revisión para el equipo.
También conviene distinguir «rechazo» de «fallo»: el primero suele ocurrir antes de la generación; el segundo puede haber generado costos. La regla concreta depende del proveedor.
5. Tareas fallidas, timeouts y resultados vencidos
Las causas de una tarea fallida incluyen error interno del upstream, anomalía de la cuenta, parámetros inválidos, fallo al descargar la imagen de referencia, interrupción de la moderación y timeout en la cola. Lee primero el campo de error; no te quedes con el texto «failed».
Hay que distinguir tres timeouts. El timeout de lectura del cliente: la solicitud puede haber llegado al servidor. El timeout de envío: la tarea puede haberse creado aunque la respuesta no haya vuelto. El timeout de consulta: la tarea sigue en ejecución pero terminó la ventana de espera.
El caso más peligroso es reenviar inmediatamente después de un timeout de envío, porque la tarea original puede existir y el resultado sería un cobro duplicado. Lo correcto es lo siguiente: incluir una clave de idempotencia o un número de solicitud de negocio al enviar; tras el timeout, consultar las tareas recientes por ese número; reintentar solo cuando se confirme que no existen. Si el proveedor no admite clave de idempotencia, aplica una ventana de deduplicación en la tabla de tareas.
El vencimiento del resultado es otro problema. Lo que se devuelve al éxito suele ser una URL temporal, con validez de minutos a días, y no debe guardarse en la base de datos como dirección de la obra. Después del éxito, transfiere de inmediato a almacenamiento de objetos; en la base de datos conserva solo tu propia ruta de almacenamiento y el ID de tarea.
6. Fallos de descarga: 403, 404 y archivos truncados
Un fallo de descarga no equivale a un fallo de generación. Los casos habituales son: URL firmada vencida que devuelve 403; resultado eliminado que devuelve 404; corte del proxy o de la red que reinicia la conexión; guardar una página HTML de error como si fuera una imagen; archivo descargado solo a medias.
La descarga debe diseñarse aparte: valida Content-Type y el tamaño del archivo; escribe primero en un archivo temporal y renombra de forma atómica al terminar; reintenta los 5xx y los errores de red; ante 403 y 404 no reintentes la generación, sino consulta el estado de la tarea para confirmar si el resultado sigue disponible. Si el proveedor ofrece varias direcciones de resultado, prepara un dominio alternativo o un canal de almacenamiento.
7. Reintentos e idempotencia: que el fallo no se convierta en doble cobro
El principio de los reintentos es clasificar, no aplicar un bucle uniforme. Ante 401, 403, 400, 422 y rechazo por moderación, no reintentes hasta corregir la configuración o el prompt; ante 429, espera según Retry-After; ante 5xx, reinicio de conexión y timeout de lectura, aplica backoff; ante timeout de envío, consulta primero la tarea y luego decide.
import random
import time
import requests
RETRYABLE = {429, 500, 502, 503, 504}
def post_with_retry(url, headers, payload, request_id, max_attempts=4):
for attempt in range(1, max_attempts + 1):
try:
resp = requests.post(
url,
headers={**headers, "Idempotency-Key": request_id},
json=payload,
timeout=(10, 60),
)
except (requests.Timeout, requests.ConnectionError):
if attempt == max_attempts:
raise
time.sleep(min(2 ** attempt + random.random(), 30))
continue
if resp.status_code in RETRYABLE:
retry_after = resp.headers.get("Retry-After", "")
wait = int(retry_after) if retry_after.isdigit() else 2 ** attempt
time.sleep(min(wait + random.random(), 60))
continue
if resp.status_code >= 400:
raise RuntimeError(f"{resp.status_code}: {resp.text[:200]}")
return resp.json()
raise RuntimeError("retry budget exhausted")
El Idempotency-Key del ejemplo es solo una forma habitual; si se admite y con qué nombre de campo debe confirmarse en la documentación del proveedor. Cuando no hay clave de idempotencia, un número de solicitud de negocio más una tabla de tareas con deduplicación logra el mismo objetivo.
8. Lista de verificación antes de abrir un ticket
- Registra la hora del incidente, la zona horaria y la duración.
- Adjunta el ID de solicitud, el ID de tarea y el número de pedido.
- Indica la dirección de la interfaz, el nombre del modelo y la versión de la API.
- Adjunta el código de estado HTTP completo y el cuerpo de la respuesta; anonimiza claves y datos personales.
- Describe los parámetros, el número de imágenes de referencia y la relación de aspecto; no escribas solo «falló la generación».
- Registra el número de reintentos, los intervalos, el entorno de red y la región de salida.
- Proporciona pasos mínimos de reproducción y el resultado de cambiar de modelo con los mismos parámetros.
- Indica el alcance: cuántas tareas fallaron y si afecta entregas en producción.
La información más útil de un ticket es el modelo concreto, la región, la franja horaria, los parámetros y tres ID de solicitud, no «la interfaz no funciona».
9. Monitoreo y prevención
Convierte los errores en métricas: por modelo, calcula la proporción de 401, 403, 429, 5xx, tareas fallidas, timeouts y descargas fallidas; registra la latencia P95; revisa a diario si las tareas fallidas se cobraron. Define alertas por umbral para los 429, la tasa de tareas fallidas y la tasa de descargas fallidas, en lugar de esperar a que lleguen las quejas.
Prevención diaria: separa claves por entorno y proyecto, pon un límite de cuota a las claves de prueba, limita la concurrencia y define un número máximo de reintentos y una cola de mensajes muertos para cada tipo de tarea. Si usas un encapsulamiento de terceros, confirma su página de estado, sus tiempos de respuesta y su plan de cese; no concentres todo el tráfico en un canal sin SLA.
Preguntas frecuentes
¿Qué hago si el 401 persiste después de cambiar la clave?
Primero confirma que la nueva clave está activa y tiene permisos sobre el modelo; después revisa el prefijo del encabezado, la URL base y la hora del sistema. Si otros modelos funcionan, el problema puede estar en el grupo de cuentas upstream.
¿Un 429 significa saldo insuficiente?
No necesariamente. Un 429 puede ser frecuencia de solicitudes, concurrencia, cuota o capacidad del grupo de cuentas. Revisa los encabezados y el cuerpo del error; solo si aparecen las palabras quota o balance es más probable que sea un problema de cuota.
¿Puedo reenviar directamente después de un timeout de tarea?
No es recomendable. Un timeout de envío no significa que la tarea no se haya creado; reenviar puede duplicar el cobro. Consulta primero por número de solicitud o ID de tarea y reintenta solo cuando confirmes que no existe; al enviar, incluye una clave de idempotencia siempre que sea posible.
¿Se puede recuperar un enlace de resultado vencido?
Depende de si el proveedor conserva el resultado. Consulta primero el estado de la tarea; si ya se limpió, normalmente solo queda regenerar. En producción, transfiere el resultado en cuanto tengas éxito para no depender de enlaces temporales.
¿Midjourney resuelve los errores de interfaces de terceros?
No. Los encapsulamientos de terceros no tienen relación de afiliación con Midjourney y el error debe investigarlo el proveedor; además, Midjourney no ofrece un canal de soporte de API pública.
Siguiente paso
Clasifica primero los errores en cinco grupos —autenticación, límite de tasa, contenido, tarea y descarga— y después decide cuáles reintentar y cuáles alertar. Si necesitas una entrada unificada, crea una clave en ZSQH AI Gateway y confirma modelos y facturación en la página de precios de modelos.
Lecturas relacionadas:
