✨ API orientada a agentes

Pistas de error estructuradas para que los agentes de AI se autocorrijan en el primer reintento

​

Descripción general

La API orientada a agentes de LemonData enriquece las respuestas de error con pistas estructuradas que los agentes de AI pueden analizar y sobre las que pueden actuar de inmediato — sin búsquedas web, sin consultar la documentación y sin conjeturas.

Cada respuesta de error incluye campos opcionales como did_you_mean, suggestions, hint, retryable y retry_after dentro del objeto estándar error. Estos campos son retrocompatibles — los clientes que no los usan no notan ninguna diferencia.

​

Campos de pistas de error

Todos los campos de pistas son extensiones opcionales dentro del objeto error:

Campo	Tipo	Descripción
did_you_mean	string	Nombre del modelo con la coincidencia más cercana
suggestions	array	Modelos recomendados con metadatos
alternatives	array	Modelos alternativos disponibles actualmente
hint	string	Guía legible por humanos/agentes sobre el siguiente paso
retryable	boolean	Si reintentar la misma solicitud puede tener éxito
retry_after	number	Segundos que se deben esperar antes de reintentar
balance_usd	number	Saldo actual de la cuenta en USD
estimated_cost_usd	number	Costo estimado de la solicitud fallida

​

Ejemplos de códigos de error

​

model_not_found (400)

Cuando un nombre de modelo no coincide con ningún modelo activo:

{
  "error": {
    "message": "Model 'gpt5' 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"},
      {"id": "claude-sonnet-4-6"}
    ],
    "hint": "Did you mean 'gpt-5.4'? Use GET https://api.lemondata.cc/v1/models to list all available models."
  }
}

La resolución de did_you_mean usa:

1. Mapeo estático de alias (a partir de datos de errores de producción)
2. Coincidencia de cadenas normalizadas (elimina guiones, no distingue mayúsculas de minúsculas)
3. Coincidencia por distancia de edición (umbral ≤ 3)

​

insufficient_balance (402)

Cuando el saldo de la cuenta es demasiado bajo para el costo estimado:

{
  "error": {
    "message": "Insufficient balance: need ~$0.3500 for claude-sonnet-4-6, but balance is $0.1200.",
    "type": "insufficient_balance",
    "code": "insufficient_balance",
    "balance_usd": 0.12,
    "estimated_cost_usd": 0.35,
    "suggestions": [
      {"id": "gpt-5-mini"},
      {"id": "deepseek-v3-2"}
    ],
    "hint": "Insufficient balance: need ~$0.3500 for claude-sonnet-4-6, but balance is $0.1200. Try a cheaper model, or top up at https://lemondata.cc/dashboard/billing."
  }
}

suggestions contiene modelos más baratos que el costo estimado a los que el agente puede cambiar.

​

all_channels_failed (503)

Cuando todos los canales upstream para un modelo no están disponibles:

{
  "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": "All channels for 'claude-opus-4-6' are temporarily unavailable. Retry in 30s or try an alternative model."
  }
}

retryable es false cuando la razón es no_channels (no hay canales configurados para este modelo). Es true solo para fallos transitorios como activaciones del circuit breaker o agotamiento de cuota.

​

rate_limit_exceeded (429)

{
  "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."
  }
}

El valor de retry_after se calcula a partir del tiempo real de restablecimiento de la ventana de rate limit.

Los endpoints compatibles con OpenAI usan los tipos de error públicos y estables de LemonData, como rate_limit_exceeded, upstream_error y all_channels_failed. Los endpoints compatibles con Anthropic y Gemini usan sus propias formas nativas de respuesta.

​

context_length_exceeded (400)

Cuando la entrada supera la ventana de contexto del modelo (error upstream, enriquecido con pistas):

{
  "error": {
    "message": "This model's maximum context length is 128000 tokens...",
    "type": "invalid_request_error",
    "code": "context_length_exceeded",
    "retryable": false,
    "suggestions": [
      {"id": "gemini-2.5-pro"},
      {"id": "claude-sonnet-4-6"}
    ],
    "hint": "Reduce your input or switch to a model with a larger context window."
  }
}

​

Encabezados de endpoint nativo

Cuando llamas a /v1/chat/completions con un modelo que tiene un endpoint nativo (Anthropic o Gemini), la respuesta exitosa incluye encabezados de optimización:

X-LemonData-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance (no format conversion).
X-LemonData-Native-Endpoint: /v1/messages

Proveedor del modelo	Endpoint sugerido	Beneficio
Anthropic (Claude)	/v1/messages	Sin conversión de formato, extended thinking, prompt caching
Google (Gemini)	/v1beta/gemini	Sin conversión de formato, grounding, configuraciones de seguridad
OpenAI	—	Chat completions ya es el formato nativo

Estos encabezados aparecen tanto en respuestas streaming como no streaming.

​

Mejoras en /v1/models

Tres campos nuevos en la extensión lemondata de cada objeto de modelo:

{
  "id": "gpt-5.4",
  "lemondata": {
    "category": "chat",
    "pricing_unit": "per_token",
    "cache_pricing": {
      "cache_read_per_1m": "1.25",
      "cache_write_per_1m": "2.50",
      "platform_cache_discount": 0.9
    }
  }
}

Campo	Valores	Descripción
category	chat, image, video, audio, tts, stt, 3d, embedding, rerank	Tipo de modelo
pricing_unit	per_token, per_image, per_second, per_request	Cómo se factura el modelo
cache_pricing	object o null	Precios de caché de prompt upstream + descuento de caché semántica de la plataforma

​

Filtrado por categoría

GET https://api.lemondata.cc/v1/models?category=chat          # Chat models only
GET https://api.lemondata.cc/v1/models?category=image         # Image generation models
GET https://api.lemondata.cc/v1/models?tag=coding&category=chat  # Coding-optimized chat models

​

llms.txt

Hay disponible una descripción general de la API legible por máquina en:

GET https://api.lemondata.cc/llms.txt

Incluye:

• Plantilla para la primera llamada con un ejemplo funcional
• Nombres comunes de modelos (generados dinámicamente a partir de datos de uso)
• Los 12 endpoints de la API
• Parámetros de filtrado para el descubrimiento de modelos
• Guía para el manejo de errores

Los agentes de AI que leen llms.txt antes de su primera llamada a la API normalmente pueden tener éxito en el primer intento.

​

Uso en código de agente

​

Python (OpenAI SDK)

from openai import OpenAI, BadRequestError

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

def smart_chat(messages, model="gpt-4o"):
    try:
        return client.chat.completions.create(
            model=model, messages=messages
        )
    except BadRequestError as e:
        error = e.body.get("error", {}) if isinstance(e.body, dict) else {}
        # Use did_you_mean for auto-correction
        if error.get("code") == "model_not_found" and error.get("did_you_mean"):
            return client.chat.completions.create(
                model=error["did_you_mean"], messages=messages
            )
        raise

​

JavaScript (OpenAI SDK)

import OpenAI from 'openai';

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

async function smartChat(messages, model = 'gpt-4o') {
  try {
    return await client.chat.completions.create({ model, messages });
  } catch (error) {
    const err = error?.error;
    if (err?.code === 'model_not_found' && err?.did_you_mean) {
      return client.chat.completions.create({
        model: err.did_you_mean, messages
      });
    }
    throw error;
  }
}

​

Principios de diseño

Fallar rápido, fallar de forma informativa

Los errores se devuelven de inmediato con todos los datos que un agente necesita para autocorregirse.

Sin auto-routing

La API nunca sustituye silenciosamente un modelo por otro diferente. El agente decide.

Sugerencias basadas en datos

Todas las recomendaciones provienen de datos de producción, no de listas codificadas manualmente.

Retrocompatible

Todos los campos de pistas son opcionales. Los clientes existentes no notan ninguna diferencia.