Referencia de Códigos de Error de API#

URL base: https://api.ideal.house
Versión: v1
Actualizado: 2026-03-06

📖 Descripción general#

Todas las respuestas de API siguen una estructura JSON unificada. Cuando ocurre un error, el campo code contendrá un código de error distinto de cero, y el campo message proporcionará una descripción legible del error.

Formato de Respuesta Unificado

{
  "code": 1001,
  "message": "Request failed",
  "data": null
}

✅ Código de Éxito#

Ejemplo

{
  "code": 0,
  "message": "success",
  "data": { }
}

❌ Códigos de Error#

🔧 Errores Generales#

🔐 Errores de Autenticación#

🛡️ Errores de Moderación de Contenido#

💰 Errores de Créditos#

📋 Resumen Completo de Códigos de Error#

📦 Ejemplos de Respuestas de Error#

1001 — Solicitud Fallida#

{
  "code": 1001,
  "message": "Request failed",
  "data": null
}

1003 — Error Interno del Servidor#

{
  "code": 1003,
  "message": "Internal server error",
  "data": null
}

1011 — Error de Parámetros#

{
  "code": 1011,
  "message": "Request parameter error: imageUrl is required",
  "data": null
}

5002 — Clave API Inválida#

{
  "code": 5002,
  "message": "Invalid API Key",
  "data": null
}

9010 — Fallo en Moderación de Contenido de Texto#

{
  "code": 9010,
  "message": "Text prompt failed content review, contains prohibited content",
  "data": null
}

9038 — Contenido Prohibido en la Salida#

{
  "code": 9038,
  "message": "Prohibited content",
  "data": null
}

9051 — Créditos Insuficientes#

{
  "code": 9051,
  "message": "Insufficient coins",
  "data": null
}

💡 Mejores Prácticas para el Manejo de Errores#

1. Verifique siempre code — No confíe únicamente en los códigos de estado HTTP; inspeccione siempre el campo code en el cuerpo de la respuesta.
2. Gestione 1001 de forma dinámica — Este es un código de error genérico; el campo message contendrá la razón específica.
3. Reintente en caso de 1003 — Los errores del lado del servidor suelen ser transitorios; implemente lógica de reintento con retroceso exponencial.
4. Valide las entradas antes de enviar — Evite errores 1011 validando los campos requeridos en el lado del cliente antes de realizar la llamada a API.
5. Moderación de contenido — Si recibe 9010 o 9038, revise su contenido según la Política de Contenido de la plataforma antes de volver a enviarlo.

© Ideal House AI — Todos los derechos reservados.