Manejo de errores

Maneja los errores de la API correctamente

​

Formato de respuesta de error

Todos los errores devuelven un formato JSON consistente con pistas Agent-First opcionales:

{
  "error": {
    "message": "Human-readable error description",
    "type": "error_type",
    "code": "error_code",
    "param": "parameter_name",
    "did_you_mean": "suggested_model",
    "suggestions": [{"id": "model-id"}],
    "hint": "Next step guidance",
    "retryable": true,
    "retry_after": 30
  }
}

Los campos base (message, type, code, param) siempre están presentes. Los campos de pistas (did_you_mean, suggestions, hint, retryable, retry_after, balance_usd, estimated_cost_usd) son extensiones opcionales para la autocorrección de agentes de IA. Consulta la guía de la API Agent-First para más detalles.

Los endpoints compatibles con OpenAI usan los tipos de error estables del gateway de LemonData. Los endpoints compatibles con Anthropic y compatibles con Gemini usan sus propias familias de errores nativas y formatos de respuesta.

​

Códigos de estado HTTP

Code	Description
400	Solicitud incorrecta - Parámetros no válidos
401	No autorizado - API key no válida o faltante
402	Pago requerido - Saldo insuficiente
403	Prohibido - Acceso denegado o modelo no permitido
404	No encontrado - Modelo o recurso no encontrado
413	Payload demasiado grande - Se excedió el tamaño de entrada o archivo
429	Demasiadas solicitudes - Se excedió el límite de tasa
500	Error interno del servidor
502	Gateway incorrecto - Error del proveedor upstream
503	Servicio no disponible - Servicio temporalmente no disponible
504	Tiempo de espera agotado del gateway - La solicitud agotó el tiempo de espera

​

Tipos de error

​

Errores de autenticación (401)

Type	Code	Description
invalid_api_key	invalid_api_key	La API key falta o no es válida
expired_api_key	expired_api_key	La API key ha sido revocada

from openai import OpenAI, AuthenticationError

try:
    response = client.chat.completions.create(...)
except AuthenticationError as e:
    print(f"Authentication failed: {e.message}")

​

Errores de pago (402)

Type	Code	Description
insufficient_balance	insufficient_balance	El saldo de la cuenta es demasiado bajo (endpoints compatibles con OpenAI)
insufficient_balance_error	insufficient_balance	El saldo de la cuenta es demasiado bajo (endpoints compatibles con Anthropic)
quota_exceeded	quota_exceeded	Se alcanzó el límite de uso de la API key

from openai import OpenAI, APIStatusError

try:
    response = client.chat.completions.create(...)
except APIStatusError as e:
    if e.status_code == 402:
        print("Please top up your account balance")

​

Errores de acceso (403)

Type	Code	Description
access_denied	access_denied	Acceso al recurso denegado
access_denied	model_not_allowed	Modelo no permitido para esta API key

{
  "error": {
    "message": "You don't have permission to access this model",
    "type": "access_denied",
    "code": "model_not_allowed"
  }
}

​

Errores de validación (400)

Type	Description
invalid_request_error	Los parámetros de la solicitud no son válidos
context_length_exceeded	La entrada es demasiado larga para el modelo
model_not_found	El modelo solicitado no existe

{
  "error": {
    "message": "Model 'invalid-model' not found",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found",
    "did_you_mean": "gpt-5.4",
    "suggestions": [{"id": "gpt-5.4"}, {"id": "gpt-5-mini"}],
    "hint": "Did you mean 'gpt-5.4'? Use GET https://api.lemondata.cc/v1/models to list all available models."
  }
}

​

Errores de límite de tasa (429)

Cuando excedes los límites de tasa:

{
  "error": {
    "message": "Rate limit: 60 rpm exceeded",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "retryable": true,
    "retry_after": 8,
    "hint": "Rate limited. Retry after 8s. Current limit: 60/min for user role."
  }
}

Encabezados incluidos:

Retry-After: 8

Tanto el encabezado Retry-After como el campo retry_after indican los segundos exactos que se deben esperar antes de reintentar.

​

Payload demasiado grande (413)

Cuando la entrada o el tamaño del archivo exceden los límites:

{
  "error": {
    "message": "Input size exceeds maximum allowed",
    "type": "invalid_request_error",
    "code": "payload_too_large"
  }
}

Causas comunes:

• Archivo de imagen demasiado grande (máx. 20MB)
• Archivo de audio demasiado grande (máx. 25MB)
• El texto de entrada excede la longitud de contexto del modelo

​

Errores upstream (502, 503)

Type	Description
upstream_error	El proveedor devolvió un error
all_channels_failed	No hay proveedores disponibles
timeout_error	La solicitud agotó el tiempo de espera

Cuando todos los canales fallan, la respuesta incluye modelos alternativos:

{
  "error": {
    "message": "Model claude-opus-4-6 temporarily unavailable",
    "code": "all_channels_failed",
    "retryable": true,
    "retry_after": 30,
    "alternatives": [
      {"id": "claude-sonnet-4-6", "status": "available", "tags": []},
      {"id": "gpt-5-mini", "status": "available", "tags": []}
    ],
    "hint": "Retry in 30s or switch to an available model."
  }
}

​

Manejo de errores en Python

from openai import OpenAI, APIError, RateLimitError, APIConnectionError

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.lemondata.cc/v1"
)

def chat_with_retry(messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model="gpt-4o",
                messages=messages
            )
        except RateLimitError as e:
            if attempt < max_retries - 1:
                import time
                time.sleep(2 ** attempt)  # Exponential backoff
                continue
            raise
        except APIConnectionError as e:
            print(f"Connection error: {e}")
            raise
        except APIError as e:
            print(f"API error: {e.status_code} - {e.message}")
            raise

​

Manejo de errores en JavaScript

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-api-key',
  baseURL: 'https://api.lemondata.cc/v1'
});

async function chatWithRetry(messages, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await client.chat.completions.create({
        model: 'gpt-4o',
        messages
      });
    } catch (error) {
      if (error instanceof OpenAI.RateLimitError) {
        if (attempt < maxRetries - 1) {
          await new Promise(r => setTimeout(r, 2 ** attempt * 1000));
          continue;
        }
      }
      throw error;
    }
  }
}

​

Mejores prácticas

Implementar exponential backoff

Cuando se aplica limitación de tasa, espera progresivamente más tiempo entre reintentos:

wait_time = 2 ** attempt  # 1s, 2s, 4s, 8s...

Configurar timeouts

Configura siempre timeouts razonables para evitar solicitudes bloqueadas:

client = OpenAI(timeout=60.0)  # 60 second timeout

Registrar errores para depuración

Registra la respuesta de error completa, incluido el ID de la solicitud, para soporte:

except APIError as e:
    logger.error(f"API Error: {e.status_code} - {e.message}")

Manejar errores específicos del modelo

Algunos modelos tienen requisitos específicos (p. ej., max tokens, formatos de imagen). Valida las entradas antes de realizar solicitudes.