Resumen
La API de APIXO utiliza dos tipos de códigos de error:
- Códigos de estado HTTP — Se devuelven de inmediato cuando la solicitud falla
- 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) │
│ │
└─────────────────────────────────────────────────────────────┘
| Tipo | Cuándo se activa | Significado | Ejemplo |
|---|
| Código de estado HTTP | Inmediatamente en la solicitud | La solicitud misma tiene problemas | 401 Clave API inválida |
| Código de fallo de tarea | Al consultar el estado | La tarea se aceptó pero falló el procesamiento | SensitiveContentDetected |
Códigos de estado HTTP
| Código | Nombre | Descripción | Acción |
|---|
200 | OK | Solicitud exitosa | Procesa la respuesta normalmente |
400 | Bad Request | Parámetros de solicitud inválidos | Comprueba el cuerpo de la solicitud |
401 | Unauthorized | Clave API inválida o faltante | Comprueba la clave API |
402 | Payment Required | Saldo insuficiente | Recarga la cuenta |
403 | Forbidden | El contenido viola la política | Modifica el contenido |
404 | Not Found | Recurso no encontrado | Comprueba el ID de modelo o tarea |
429 | Too Many Requests | Límite de tasa excedido | Espera y reintenta |
500 | Server Error | Error interno del servidor | Reintenta más tarde |
503 | Service Unavailable | Servicio temporalmente no disponible | Reintenta 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
| failCode | Descripción | Solución |
|---|
SensitiveContent | El contenido viola la política | Modifica el prompt, evita contenido sensible |
SensitiveContentDetected | El contenido se marcó como violación | Ajusta el contenido del prompt |
InputImageSensitiveContentDetected | La imagen de entrada contiene violación | Usa una imagen conforme |
InputOutputSensitiveContentDetected | La entrada o salida contiene contenido sensible | Reintenta con entrada diferente |
NSFW | Se detectó contenido NSFW | Usa entrada conforme a la política |
ProhibitedContentDetected | Se detectó contenido prohibido | Prueba con entrada diferente |
Errores de prompt
| failCode | Descripción | Solución |
|---|
PromptLengthExceeded | El prompt excede el límite | Acorta el prompt |
PromptInvalid | Prompt inválido o rechazado | Comprueba formato y contenido del prompt |
| failCode | Descripción | Solución |
|---|
ImageFormatIncorrect | Formato de imagen incorrecto | Usa JPEG, PNG o WebP |
InvalidImageSize | Dimensiones de imagen inválidas | Comprueba requisitos de tamaño |
Upload error | La imagen excede el límite de 10MB | Comprime la imagen a menos de 10MB |
INVALID_IMAGE_URL | No se puede acceder a la URL de imagen | Comprueba accesibilidad de la URL |
INVALID_LORA_URL | No se puede descargar el modelo LoRA | Comprueba la URL de LoRA |
Limitación de tasa y cuota
| failCode | Descripción | Solución |
|---|
RateLimited | Límite de tasa, reintenta más tarde | Reduce la frecuencia, espera y reintenta |
RateLimitExceeded | Límite de tasa excedido | Reintenta más tarde |
InsufficientQuota | Cuota insuficiente | Comprueba el saldo de la cuenta |
Errores de procesamiento y sistema
| failCode | Descripción | Solución |
|---|
Timeout | Timeout de respuesta | Reintenta más tarde |
Task TimeOut | Tarea expirada, generación fallida | Cambia a otra tarea |
BadRequest | Parámetros obligatorios faltantes | Comprueba parámetros de la solicitud |
MissingParameter | Parámetro obligatorio faltante | Consulta la documentación de la API, añade el parámetro |
Ejemplos de respuestas de error
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) | No | Corrige parámetros y reintenta |
401 (Auth fallida) | No | Comprueba la clave API |
429 (Límite de tasa) | Sí | Backoff exponencial, espera 60s y reintenta |
500 (Error servidor) | Sí | Backoff exponencial, máx. 3 veces |
504 (Timeout) | Sí | Espera y reintenta, máx. 3 veces |
| Violación de contenido | No | Modifica el contenido y reintenta |
| Error de imagen | No | Corrige 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
| failCode | Descripción |
|---|
SensitiveContentDetected | Contenido marcado por OpenAI como violación |
InputImageSensitiveContentDetected | Imágenes con personas reales no admitidas |
MidJourney
| failCode | Descripción |
|---|
Website TimeOut | Sitio web de MidJourney no responde tras varios intentos |
INVALID_TASK_ID | ID de tarea anterior inválido para upscale/vary |
Seedream (ByteDance)
| failCode | Descripción |
|---|
outputimagesensitivecontentdetected | La imagen de salida contiene contenido sensible |
InvalidImageSize | Dimensiones 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