Codigos de Error

La API de ZUI GEN usa codigos de estado HTTP estandar junto con codigos de error especificos para indicar el resultado de las peticiones.

Formato de Error

Todas las respuestas de error siguen el mismo formato:

Respuesta de errorjson

{
  "error": "Mensaje descriptivo del error",
  "code": "ERROR_CODE"
}

Codigos HTTP

Codigo	Significado	Descripcion
`200`	OK	Peticion exitosa
`400`	Bad Request	Parametros invalidos o faltantes
`401`	Unauthorized	API Key invalida o faltante
`402`	Payment Required	Creditos insuficientes
`403`	Forbidden	No tienes permiso para esta accion
`404`	Not Found	Recurso no encontrado
`429`	Too Many Requests	Rate limit excedido
`500`	Internal Error	Error interno del servidor

Errores de Autenticacion

Codigo	HTTP	Descripcion	Solucion
`MISSING_API_KEY`	401	No se envio API Key	Incluir header Authorization
`INVALID_API_KEY_FORMAT`	401	Formato de key incorrecto	La key debe empezar con zui_
`INVALID_API_KEY`	401	Key no existe o revocada	Verificar key en el panel
`SUBSCRIPTION_REQUIRED`	403	No hay suscripcion activa	Activar un plan de suscripcion

Errores de Generacion

Codigo	HTTP	Descripcion	Solucion
`MISSING_MODEL`	400	Falta el parametro model	Incluir model en el body
`INVALID_MODEL`	400	El modelo no existe	Consultar GET /models
`MISSING_PROMPT`	400	Falta el prompt de texto	Incluir prompt en el body
`MISSING_IMAGE`	400	El modelo requiere imagen	Incluir image_url
`INVALID_IMAGE_URL`	400	URL de imagen invalida	Verificar que la URL es accesible
`INSUFFICIENT_CREDITS`	402	No hay creditos suficientes	Recargar creditos o cambiar plan
`CONTENT_MODERATION`	400	Contenido rechazado por moderacion	Modificar el prompt
`GENERATION_ERROR`	500	Error al procesar	Reintentar la peticion

Errores de Tareas

Codigo	HTTP	Descripcion	Solucion
`TASK_NOT_FOUND`	404	Tarea no encontrada	Verificar task_id y permisos

Errores de Rate Limit

Codigo	HTTP	Descripcion	Solucion
`RATE_LIMIT_EXCEEDED`	429	Demasiadas peticiones	Esperar y usar backoff exponencial

Manejo de Errores

Ejemplo de como manejar errores correctamente:

Error handlingtypescript

interface ApiError {
  error: string;
  code: string;
}
async function generateWithErrorHandling(
  model: string,
  prompt: string
) {
  try {
    const response = await fetch('https://gen.zui.es/api/v1/generate', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ model, prompt }),
    });
    if (!response.ok) {
      const error: ApiError = await response.json();
      switch (error.code) {
        case 'INSUFFICIENT_CREDITS':
          // Notificar al usuario que necesita mas creditos
          throw new Error('No tienes suficientes creditos');
        case 'INVALID_MODEL':
          // Modelo no disponible
          throw new Error('El modelo seleccionado no esta disponible');
        case 'RATE_LIMIT_EXCEEDED':
          // Implementar retry con backoff
          await new Promise(r => setTimeout(r, 5000));
          return generateWithErrorHandling(model, prompt);
        case 'CONTENT_MODERATION':
          throw new Error('El contenido fue rechazado por moderacion');
        default:
          throw new Error(error.error || 'Error desconocido');
      }
    }
    return await response.json();
  } catch (error) {
    if (error instanceof TypeError) {
      // Error de red
      throw new Error('Error de conexion. Verifica tu internet.');
    }
    throw error;
  }
}

Mejores Practicas

Siempre verifica el codigo HTTP antes de procesar la respuesta.
Implementa retry con backoff exponencial para errores 429 y 5xx.
Guarda logs de errores para debugging.
Muestra mensajes de error amigables al usuario final.
No expongas detalles tecnicos de errores en interfaces publicas.