Skip to Content
DocumentaciónGuíasManejo de errores

Manejo de errores

Esta guía presenta el formato de respuesta de error de la API de OfoxAI, los escenarios de error comunes y las estrategias de manejo recomendadas.

Formato de respuesta de error

Todas las respuestas de error siguen un formato JSON unificado:

{
  "error": {
    "code": "invalid_api_key",
    "message": "La API Key proporcionada es inválida, por favor verifique e intente de nuevo.",
    "type": "authentication_error"
  }
}

Códigos de estado HTTP

CódigoTipoDescripción¿Reintentar?
400invalid_request_errorParámetros de solicitud incorrectosNo, modifique los parámetros
401authentication_errorAPI Key inválida o faltanteNo, verifique la API Key
403permission_errorPermisos insuficientesNo, verifique los permisos de la cuenta
404not_found_errorModelo o recurso no encontradoNo, verifique el ID del modelo
429rate_limit_errorLímite de tasa alcanzadoSí, espere y reintente
500internal_errorError interno del servidorSí, reintente más tarde
502upstream_errorError del proveedor upstreamSí, cambie de modelo o reintente
503service_unavailableServicio temporalmente no disponibleSí, reintente más tarde

Errores comunes y soluciones

401 — API Key inválida

{"error": {"code": "invalid_api_key", "message": "The API key provided is invalid."}}

Solución:

  • Verifique que la API Key se haya copiado correctamente (incluyendo el prefijo sk-)
  • Confirme que la Key no haya expirado o sido deshabilitada
  • Verifique que las variables de entorno se carguen correctamente

429 — Límite de tasa

{"error": {"code": "rate_limit_exceeded", "message": "Rate limit reached. Please retry after 1s."}}

Solución:

  • Verifique x-ratelimit-reset-requests en los headers de respuesta
  • Implemente reintento con retroceso exponencial
  • Si necesita cuotas más altas, contacte a soporte para solicitar un ajuste

502 — Error upstream

{"error": {"code": "upstream_error", "message": "The upstream provider returned an error."}}

Solución:

  • Use respaldo automático para cambiar automáticamente a un modelo alternativo
  • Reintente más tarde
  • Verifique la página de estado del proveedor del modelo

Estrategia de reintento

Se recomienda usar una estrategia de retroceso exponencial (Exponential Backoff):

retry.py
import time
import random
from openai import OpenAI, APIError, RateLimitError, APIConnectionError
 
client = OpenAI(
    base_url="https://api.ofox.ai/v1",
    api_key="<su OFOXAI_API_KEY>"
)
 
def chat_with_retry(max_retries=5, **kwargs):
    """Wrapper de reintento con retroceso exponencial"""
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(**kwargs)
 
        except RateLimitError:
            # 429: esperar y reintentar
            wait = (2 ** attempt) + random.uniform(0, 1)
            print(f"Límite de tasa alcanzado, reintentando en {wait:.1f}s...")
            time.sleep(wait)
 
        except APIConnectionError:
            # Error de red: esperar brevemente y reintentar
            wait = 2 ** attempt
            print(f"Error de conexión, reintentando en {wait}s...")
            time.sleep(wait)
 
        except APIError as e:
            if e.status_code and e.status_code >= 500:
                # 5xx: error del servidor, reintentar
                wait = 2 ** attempt
                time.sleep(wait)
            else:
                # 4xx: error del cliente, no reintentar
                raise
 
    raise Exception(f"Fallo después de {max_retries} reintentos")
 
# Uso
response = chat_with_retry(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Hola"}]
)

Configuración de timeout

Se recomienda establecer un tiempo de espera razonable para las llamadas API:

# Python OpenAI SDK
client = OpenAI(
    base_url="https://api.ofox.ai/v1",
    api_key="<su OFOXAI_API_KEY>",
    timeout=60.0,  # Timeout de 60 segundos
    max_retries=3  # Reintento integrado del SDK
)
// TypeScript OpenAI SDK
const client = new OpenAI({
  baseURL: 'https://api.ofox.ai/v1',
  apiKey: '<su OFOXAI_API_KEY>',
  timeout: 60000,  // Timeout de 60 segundos
  maxRetries: 3    // Reintento integrado del SDK
})

Para solicitudes en streaming se recomienda un timeout más largo (120-300 segundos), ya que el modelo puede necesitar más tiempo para generar el contenido completo.

Mejores prácticas

  1. Distinga errores reintentables y no reintentables — Los 4xx generalmente requieren modificar la solicitud; los 5xx se pueden reintentar
  2. Use retroceso exponencial — Evite reintentos frecuentes durante la limitación de tasa
  3. Establezca un máximo de reintentos — Prevenga reintentos infinitos
  4. Registre los errores — Facilite la resolución de problemas
  5. Configure respaldo automático — Use el parámetro provider.fallback de OfoxAI para cambiar de modelo automáticamente
  6. Monitoree la tasa de errores — Observe las tendencias de errores en la consola
Last updated on
Salida estructuradaEnrutamiento de proveedores