Saltar al contenido principal

Resumen

La API de APIXO utiliza dos tipos de códigos de error:
  1. Códigos de estado HTTP — Se devuelven de inmediato cuando la solicitud falla
  2. Códigos de fallo de tarea — Se devuelven al consultar el estado cuando falla el procesamiento
┌─────────────────────────────────────────────────────────────┐
│                      API Request Flow                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  POST /generateTask/{model}                                 │
│         │                                                   │
│         ├── Fail ──→ HTTP Status Code (400/401/429...)      │
│         │           Request rejected immediately             │
│         │                                                   │
│         └── Success ──→ 200 + taskId                        │
│                        Request accepted, task processing    │
│                             │                               │
│                             ▼                               │
│  GET /statusTask/{model}?taskId=xxx                         │
│         │                                                   │
│         ├── state: success ──→ resultUrls                   │
│         │                                                   │
│         └── state: failed ──→ Task Failure Code             │
│                               (failCode/failMsg)             │
│                                                             │
└─────────────────────────────────────────────────────────────┘
TipoCuándo se activaSignificadoEjemplo
Código de estado HTTPInmediatamente en la solicitudLa solicitud misma tiene problemas401 Clave API inválida
Código de fallo de tareaAl consultar el estadoLa tarea se aceptó pero falló el procesamientoSensitiveContentDetected

Códigos de estado HTTP

CódigoNombreDescripciónAcción
200OKSolicitud exitosaProcesa la respuesta normalmente
400Bad RequestParámetros de solicitud inválidosComprueba el cuerpo de la solicitud
401UnauthorizedClave API inválida o faltanteComprueba la clave API
402Payment RequiredSaldo insuficienteRecarga la cuenta
403ForbiddenEl contenido viola la políticaModifica el contenido
404Not FoundRecurso no encontradoComprueba el ID de modelo o tarea
429Too Many RequestsLímite de tasa excedidoEspera y reintenta
500Server ErrorError interno del servidorReintenta más tarde
503Service UnavailableServicio temporalmente no disponibleReintenta más tarde

Códigos de fallo de tarea

Cuando una tarea falla, la respuesta incluye failCode y failMsg:
{
  "code": 200,
  "message": "success",
  "data": {
    "state": "failed",
    "failCode": "SensitiveContentDetected",
    "failMsg": "Your content was flagged by OpenAI as violating content policies."
  }
}

Violaciones de política de contenido

failCodeDescripciónSolución
SensitiveContentEl contenido viola la políticaModifica el prompt, evita contenido sensible
SensitiveContentDetectedEl contenido se marcó como violaciónAjusta el contenido del prompt
InputImageSensitiveContentDetectedLa imagen de entrada contiene violaciónUsa una imagen conforme
InputOutputSensitiveContentDetectedLa entrada o salida contiene contenido sensibleReintenta con entrada diferente
NSFWSe detectó contenido NSFWUsa entrada conforme a la política
ProhibitedContentDetectedSe detectó contenido prohibidoPrueba con entrada diferente

Errores de prompt

failCodeDescripciónSolución
PromptLengthExceededEl prompt excede el límiteAcorta el prompt
PromptInvalidPrompt inválido o rechazadoComprueba formato y contenido del prompt

Errores de imagen/media

failCodeDescripciónSolución
ImageFormatIncorrectFormato de imagen incorrectoUsa JPEG, PNG o WebP
InvalidImageSizeDimensiones de imagen inválidasComprueba requisitos de tamaño
Upload errorLa imagen excede el límite de 10MBComprime la imagen a menos de 10MB
INVALID_IMAGE_URLNo se puede acceder a la URL de imagenComprueba accesibilidad de la URL
INVALID_LORA_URLNo se puede descargar el modelo LoRAComprueba la URL de LoRA

Limitación de tasa y cuota

failCodeDescripciónSolución
RateLimitedLímite de tasa, reintenta más tardeReduce la frecuencia, espera y reintenta
RateLimitExceededLímite de tasa excedidoReintenta más tarde
InsufficientQuotaCuota insuficienteComprueba el saldo de la cuenta

Errores de procesamiento y sistema

failCodeDescripciónSolución
TimeoutTimeout de respuestaReintenta más tarde
Task TimeOutTarea expirada, generación fallidaCambia a otra tarea
BadRequestParámetros obligatorios faltantesComprueba parámetros de la solicitud
MissingParameterParámetro obligatorio faltanteConsulta la documentación de la API, añade el parámetro

Ejemplos de respuestas de error

Error HTTP (devolución inmediata)

400 - Error de parámetro
{
  "code": 400,
  "message": "Prompt exceeds provider limit (max 2000 chars)",
  "data": null
}
401 - Autenticación fallida
{
  "code": 401,
  "message": "Invalid or missing API key",
  "data": null
}
429 - Límite de tasa
{
  "code": 429,
  "message": "Provider rate limited, please retry later",
  "data": null
}
504 - Timeout
{
  "code": 504,
  "message": "Provider timeout, please retry later",
  "data": null
}

Fallo de tarea (al consultar estado)

Violación de contenido
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "failed",
    "failCode": "SensitiveContentDetected",
    "failMsg": "Your content was flagged by OpenAI as violating content policies.",
    "createTime": 1767965610929,
    "completeTime": 1767965652317
  }
}
Contenido NSFW
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "failed",
    "failCode": "NSFW",
    "failMsg": "NSFW, Try different input please.",
    "createTime": 1767965610929,
    "completeTime": 1767965652317
  }
}
Error de formato de imagen
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "failed",
    "failCode": "ImageFormatIncorrect",
    "failMsg": "Image format is incorrect",
    "createTime": 1767965610929,
    "completeTime": 1767965652317
  }
}

Buenas prácticas de manejo de errores

Solo 429, 500 y 504 son candidatos para reintento automático. Todos los demás requieren corregir la solicitud primero.

1. Estrategia de reintento

Tipo de error¿Reintentar?Estrategia
400 (Error de parámetro)NoCorrige parámetros y reintenta
401 (Auth fallida)NoComprueba la clave API
429 (Límite de tasa)Backoff exponencial, espera 60s y reintenta
500 (Error servidor)Backoff exponencial, máx. 3 veces
504 (Timeout)Espera y reintenta, máx. 3 veces
Violación de contenidoNoModifica el contenido y reintenta
Error de imagenNoCorrige la imagen y reintenta

2. Ejemplo de backoff exponencial

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.code === 429 || error.code >= 500) {
        const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
  throw new Error('Max retries exceeded');
}

3. Consejos de moderación de contenido

La moderación de contenido la gestionan los proveedores de IA aguas arriba. Las violaciones no pueden apelarse a través de APIXO — modifica tu contenido y reenvía.
Para evitar errores de violación de contenido:
  • Evita violencia, pornografía, contenido políticamente sensible
  • Comprueba que las imágenes de entrada cumplan la política
  • Usa descripciones claras y específicas, evita expresiones ambiguas
  • Prueba primero con contenido simple y seguro

4. Monitoreo y registro

Se recomienda registrar para depuración:
  • taskId — Identificador único de la tarea
  • failCode — Código de fallo
  • failMsg — Mensaje de fallo
  • Parámetros de la solicitud (sanitizados)

Errores específicos de proveedor

OpenAI

failCodeDescripción
SensitiveContentDetectedContenido marcado por OpenAI como violación
InputImageSensitiveContentDetectedImágenes con personas reales no admitidas

MidJourney

failCodeDescripción
Website TimeOutSitio web de MidJourney no responde tras varios intentos
INVALID_TASK_IDID de tarea anterior inválido para upscale/vary

Seedream (ByteDance)

failCodeDescripción
outputimagesensitivecontentdetectedLa imagen de salida contiene contenido sensible
InvalidImageSizeDimensiones de imagen inválidas

FAQ

P: Recibí error 429, ¿cuánto debo esperar?
R: Espera 60 segundos y reintenta, o usa estrategia de backoff exponencial.
P: ¿Cómo evitar el error PromptLengthExceeded?
R: Cada modelo tiene límites diferentes de longitud de prompt; consulta la documentación del modelo. Generalmente mantén menos de 2000 caracteres.
P: ¿Puedo apelar el error SensitiveContentDetected?
R: Es el resultado de moderación del proveedor de IA aguas arriba. Se recomienda modificar el contenido y reenviar.
P: ¿Qué hacer con errores 5xx?
R: Son problemas temporales del servidor. Usa reintento con backoff exponencial, máx. 3 veces. Si persiste, contacta con soporte.
¿Por qué el estado de la tarea devuelve 200 pero state es failed? HTTP 200 significa que la solicitud API en sí tuvo éxito, pero la tarea de generación falló. El error real está en failCode y failMsg, no en el código de estado HTTP.
P: ¿Por qué el estado de la tarea devuelve 200 pero state es failed? R: HTTP 200 significa que la solicitud API tuvo éxito, pero la ejecución de la tarea falló (ej. violación de contenido). La información del error real está en failCode y failMsg.

Soporte

¿Errores persistentes? Contacta con soporte con:
  • taskId — ID de la tarea fallida
  • failCode — Código de error
  • Parámetros de la solicitud (sanitizados)
  • Hora de ocurrencia del error
Soporte técnico: support@apixo.ai