Manejo de Errores en la API LunaVerseX

Códigos de Estado HTTP

Nuestra API utiliza códigos de estado HTTP estándar para indicar el resultado de una solicitud:

Estructura de la Respuesta de Error

Cuando la API devuelve un error (generalmente un código de estado 4xx o 5xx), el cuerpo de la respuesta será un objeto JSON que proporciona más detalles sobre el problema. La estructura típica es la siguiente:

{
  "error": {
    "type": "invalid_request_error",
    "message": "El parámetro 'model' es obligatorio y no fue proporcionado.",
    "code": "missing_parameter",
    "param": "model" // Opcional: el parámetro específico que causó el error
  }
}
                                

{
  "error": {
    "type": "invalid_request_error",
    "message": "El parámetro 'model' es obligatorio y no fue proporcionado.",
    "code": "missing_parameter",
    "param": "model"
  }
}
                                

• error.type: Una cadena que identifica el tipo general de error (ver "Tipos de Errores Comunes" más abajo).
• error.message: Una descripción legible por humanos del error. Este mensaje está sujeto a cambios y no debe ser parseado programáticamente.
• error.code (opcional): Un código breve y específico para el error, útil para el manejo programático.
• error.param (opcional): Si el error está relacionado con un parámetro específico en la solicitud, este campo indicará el nombre de dicho parámetro.

Tipos de Errores Comunes

A continuación, se describen algunos de los tipos de error (`error.type`) más comunes que puedes encontrar:

• invalid_request_error
  Indica que la solicitud tiene un formato incorrecto o le faltan parámetros obligatorios. Revisa la documentación del endpoint específico y asegúrate de que tu solicitud cumpla con los requisitos. El campo error.param a menudo te ayudará a identificar el problema.
• authentication_error
  Ocurre si tu API Key es incorrecta, no se proporcionó, o ha expirado. Verifica que estés usando una API Key válida y que la estés incluyendo correctamente en el encabezado `Authorization`.
• permission_error
  Indica que la API Key utilizada no tiene los permisos necesarios para acceder al recurso o realizar la acción solicitada. Esto puede suceder si intentas acceder a un modelo o funcionalidad que no está incluido en tu plan actual.
• not_found_error
  El recurso solicitado no existe. Esto puede ocurrir si intentas acceder a un endpoint incorrecto o a un objeto (como un ID de modelo específico) que no se encuentra.
• rate_limit_error
  Has excedido el número de solicitudes permitidas en un período de tiempo determinado. Consulta los encabezados de respuesta `X-RateLimit-*` o la sección de Límites de Tasa para más información. Considera implementar un backoff exponencial en tus reintentos.
• api_error
  Indica un problema inesperado en los servidores de LunaVerseX. Estos errores son poco comunes. Si persisten, por favor, contacta a nuestro equipo de soporte. Es una buena práctica reintentar estas solicitudes después de una breve espera.

Ejemplo de Manejo de Errores en Python

Al usar la librería requests en Python, puedes capturar errores HTTP y acceder al cuerpo de la respuesta para obtener más detalles:

import requests
import json
import os

API_KEY = os.getenv("LUNAVERSEX_API_KEY", "TU_API_KEY_INVALIDA_PARA_PRUEBA") 
API_URL = "https://api.lunaversex.com/v1/chat" 
# ... (más código)
                                

import requests
import json
import os

API_KEY = os.getenv("LUNAVERSEX_API_KEY", "TU_API_KEY_INVALIDA_PARA_PRUEBA") 
API_URL = "https://api.lunaversex.com/v1/chat" 

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Payload incorrecto a propósito (falta el modelo)
payload = {
    "messages": [{"role": "user", "content": "Hola"}],
    "stream": False
}

print("--- Intentando solicitud con payload incorrecto ---")
try:
    response = requests.post(API_URL, headers=headers, json=payload, timeout=10)
    
    # Esto lanzará una excepción para códigos 4xx/5xx
    response.raise_for_status() 

    print("Respuesta exitosa (esto no debería ocurrir con payload incorrecto):")
    print(json.dumps(response.json(), indent=2, ensure_ascii=False))

except requests.exceptions.HTTPError as http_err:
    print(f"\nSe recibió un error HTTP: {http_err}")
    print(f"Código de Estado: {response.status_code}")
    try:
        error_details = response.json() # Intenta parsear el cuerpo del error como JSON
        print("Detalles del Error (JSON):")
        print(json.dumps(error_details, indent=2, ensure_ascii=False))
        
        # Acceder a campos específicos del error
        if "error" in error_details:
            error_type = error_details["error"].get("type")
            error_message = error_details["error"].get("message")
            error_param = error_details["error"].get("param")
            print(f"\nTipo de error API: {error_type}")
            print(f"Mensaje API: {error_message}")
            if error_param:
                print(f"Parámetro problemático: {error_param}")

    except json.JSONDecodeError:
        # Si el cuerpo del error no es JSON válido
        print("El cuerpo de la respuesta del error no es JSON válido:")
        print(response.text)
except requests.exceptions.ConnectionError as conn_err:
    print(f"\nError de Conexión: No se pudo conectar a {API_URL}. Verifica tu conexión a internet o la URL. ({conn_err})")
except requests.exceptions.Timeout as timeout_err:
    print(f"\nError de Timeout: La solicitud a {API_URL} tardó demasiado en responder. ({timeout_err})")
except requests.exceptions.RequestException as req_err:
    # Para otros errores relacionados con la solicitud (ej. URL mal formada)
    print(f"\nError General de Solicitud: {req_err}")
except Exception as e:
    print(f"\nOcurrió un error inesperado no relacionado con la solicitud: {e}")
                                

Este ejemplo utiliza response.raise_for_status(), que es una forma conveniente de generar una excepción si la respuesta HTTP indica un error. Luego, en el bloque `except requests.exceptions.HTTPError`, puedes acceder a `response.status_code` y `response.json()` (o `response.text`) para obtener más información.

Mejores Prácticas para el Manejo de Errores

• Monitoreo y Logging: Registra los errores de la API en tu sistema de logging. Esto es invaluable para la depuración y para identificar problemas recurrentes.
• Reintentos Inteligentes: Para errores transitorios (como 5xx o rate_limit_error), implementa una estrategia de reintentos con backoff exponencial y un número máximo de intentos. No reintentes errores 4xx que indican un problema con tu solicitud a menos que puedas corregirla.
• Feedback al Usuario: Proporciona mensajes de error claros y útiles a tus usuarios finales cuando algo sale mal, sin exponer detalles sensibles de la API.
• Configuración de Timeouts: Establece timeouts apropiados para tus solicitudes API para evitar que tu aplicación espere indefinidamente.
• Uso de SDKs: Si proporcionamos SDKs oficiales, considera usarlos, ya que a menudo incluyen utilidades para el manejo de errores.
• Pruebas Exhaustivas: Prueba tu lógica de manejo de errores simulando diferentes respuestas de error de la API.

¿Necesitas Ayuda?

Si encuentras errores persistentes que no puedes resolver o crees que hay un problema con nuestra API, no dudes en contactar a nuestro equipo de soporte. Por favor, incluye la mayor cantidad de detalles posible, como el ID de la solicitud (si está disponible en los encabezados de respuesta), el cuerpo del error y los pasos para reproducir el problema.