Integrar Claude API en Producción: Lo Que Ojalá Hubiera Sabido Antes

He integrado Claude API en varios proyectos en producción — un SaaS de specs IA, un ERP artesano con procesamiento de voz, un motor de presupuestos automatizado. Aquí lo que no anticipé, y lo que hago diferente ahora.

No Tratar la API como Infalible

Primer error clásico: escribir código que asume que la API siempre responde correctamente. En producción, los timeouts existen, los rate limits existen, los errores 529 existen.

Mi wrapper base:

async function callClaude(params: MessageCreateParams, retries = 3): Promise<Message> {
  for (let attempt = 0; attempt < retries; attempt++) {
    try {
      return await anthropic.messages.create(params);
    } catch (err) {
      if (attempt === retries - 1) throw err;
      if (isRetryable(err)) {
        await sleep(exponentialBackoff(attempt));
        continue;
      }
      throw err;
    }
  }
  throw new Error('unreachable');
}

function isRetryable(err: unknown): boolean {
  return err instanceof APIError && [429, 529].includes(err.status);
}

Sin retry con backoff exponencial, un pico de carga de Anthropic puede tumbar tu funcionalidad.

El Streaming Cambia la UX, No Solo la Perf

El streaming no es solo una optimización de rendimiento — es una decisión de UX. Un usuario que ve el texto aparecer progresivamente tolera 8 segundos. El mismo usuario esperando un spinner durante 8 segundos abandona a los 3.

Para Next.js, uso Server-Sent Events nativos:

// app/api/generate/route.ts
export async function POST(req: Request) {
  const stream = anthropic.messages.stream({
    model: 'claude-sonnet-4-6',
    max_tokens: 1024,
    messages: [{ role: 'user', content: await req.text() }],
  });

  return new Response(stream.toReadableStream(), {
    headers: { 'Content-Type': 'text/event-stream' },
  });
}

Modelar los Costes Antes de Escalar

El coste de un LLM en producción no es lineal con los usuarios — depende de la longitud del contexto, el modelo y el patrón de uso.

Lo que mido en cada llamada:

const usage = response.usage;
const cost = (usage.input_tokens * 3 + usage.output_tokens * 15) / 1_000_000; // Sonnet pricing

En un agente que procesa 100 documentos por día con 4.000 tokens de contexto medio, la diferencia entre Sonnet y Haiku es ~150€/mes. Vale la pena pensar en la granularidad del modelo por tarea.

Separar las Llamadas por Complejidad de Tarea

Patrón que uso en todos mis proyectos ahora: routing por complejidad.

const model = task.complexity === 'high'
  ? 'claude-sonnet-4-6'
  : 'claude-haiku-4-5-20251001';

Extracción de entidades, clasificación, resúmenes cortos → Haiku. Razonamiento complejo, generación de specs, análisis crítico → Sonnet. Reduce costes un 60-70% sin degradación visible para el usuario.

Gestionar el Contexto Largo Sin Reventar el Presupuesto

En el ERP artesano, las conversaciones pueden alcanzar 20+ intercambios. Enviar todo el historial en cada llamada multiplica los costes por 10 rápidamente.

Mi estrategia: ventana deslizante + resumen de contexto.

function buildContext(messages: Message[], maxTokens = 8000): Message[] {
  const recent = messages.slice(-6); // últimos 3 intercambios siempre presentes
  const olderTokens = estimateTokens(messages.slice(0, -6));

  if (olderTokens > maxTokens) {
    const summary = await summarizeHistory(messages.slice(0, -6));
    return [{ role: 'user', content: `[Resumen conversación: ${summary}]` }, ...recent];
  }
  return messages;
}

Lo Que Hago Sistemáticamente Ahora

• Log de cada llamada: prompt, modelo, tokens, latencia, coste estimado
• Timeout explícito: 30s máximo, sin requests colgadas indefinidamente
• Validación del formato de salida antes de pasarlo al código siguiente
• Alertas de coste: notificación si el gasto supera un umbral diario
• Tests de edge cases: input vacío, muy largo, en idioma incorrecto

Integrar una API LLM en producción se parece finalmente a cualquier integración de API externa — con una capa extra de no-determinismo que exige más tests y más monitorización.