Control de costos de Claude Code/API: presupuestos, alertas y límites

Claude Code se vuelve mucho más fácil de adoptar cuando puedes explicar el costo antes de que llegue la factura. El gasto no depende de un solo número: influyen el tamaño del contexto, los archivos leídos, la longitud de la respuesta, el modelo, los aciertos de prompt caching y si estás usando una suscripción de Claude o facturación directa por API.

Esta guía fue revisada contra fuentes oficiales el 2026-06-03: precios de la API de Anthropic, gestión de costos de Claude Code, prompt caching, conteo de tokens y Usage and Cost API. Los precios cambian, así que confirma siempre los números oficiales antes de comprar o presupuestar para un cliente.

Modelo mental para principiantes

Concepto	Significado	Impacto en costo
Tokens	Unidades que Claude lee y escribe	Archivos, logs, prompts y código largo aumentan el gasto
Contexto	Historial, archivos leídos, CLAUDE.md y herramientas	El contexto viejo se vuelve a pagar en solicitudes posteriores
Prompt cache	Reutilización de un prefijo repetido	Un cache hit vuelve mucho más barata la entrada repetida
Límite	Presupuesto por tarea, día, persona o workspace	Evita que un flujo útil se convierta en gasto abierto

costo estimado = tokens de entrada * tarifa de entrada
               + tokens de escritura de caché * tarifa de escritura
               + tokens leídos de caché * tarifa de lectura
               + tokens de salida * tarifa de salida

Al 2026-06-03, la tabla oficial lista Sonnet 4.6 a $3 por millón de tokens de entrada y $15 por millón de salida. Haiku 4.5 está a $1 y $5. Opus 4.8/4.7/4.6 está a $5 y $25. Las lecturas de caché cuestan 10% de la tarifa base de entrada, y las escrituras de caché de 5 minutos cuestan 1.25x.

La salida suele ser el gasto que se escapa. En vez de pedir “explica todo con detalle”, pide “máximo 5 hallazgos, ordenados por severidad, dos líneas cada uno”.

Flujo de control

flowchart LR
  A["Definir tarea"] --> B["Reducir entrada"]
  B --> C["Elegir modelo"]
  C --> D["Estimar tokens"]
  D --> E{"Dentro del presupuesto?"}
  E -- "Sí" --> F["Ejecutar Claude"]
  E -- "No" --> B
  F --> G["Registrar usage"]
  G --> H{"Umbral superado?"}
  H -- "Sí" --> I["Detener, alertar o bajar modelo"]
  H -- "No" --> A

En Claude Code, usa /usage y /context antes de que la sesión se vuelva pesada. Usa /clear al cambiar de tarea y /compact cuando quieras conservar decisiones sin arrastrar todo el historial. El importe de /usage es una estimación local; la facturación autoritativa vive en Console y, para organizaciones, en reportes de Usage and Cost.

Ejemplo 1: estimador mensual

Este script no llama a la API. Calcula el costo mensual a partir del uso diario en MTok.

// claude-cost-estimator.mjs
const RATES = {
  opus48: { input: 5, output: 25, cacheRead: 0.5 },
  sonnet46: { input: 3, output: 15, cacheRead: 0.3 },
  haiku45: { input: 1, output: 5, cacheRead: 0.1 },
};

const [model = "sonnet46", days = "22", input = "0.25", output = "0.06", cacheRead = "0.20"] =
  process.argv.slice(2);

if (!RATES[model]) {
  throw new Error(`Unknown model: ${model}`);
}

const rate = RATES[model];
const dailyUsd =
  Number(input) * rate.input +
  Number(output) * rate.output +
  Number(cacheRead) * rate.cacheRead;

console.log({
  model,
  workDays: Number(days),
  dailyUsd: Number(dailyUsd.toFixed(4)),
  monthlyUsd: Number((dailyUsd * Number(days)).toFixed(2)),
});

node claude-cost-estimator.mjs sonnet46 22 0.25 0.06 0.20
node claude-cost-estimator.mjs haiku45 22 0.25 0.06 0.20

La idea no es adivinar la factura exacta, sino saber si el flujo se parece más a $15, $50 o $500 al mes. Añade 20-30% de margen por herramientas, reintentos, cache writes y respuestas más largas de lo previsto.

Ejemplo 2: wrapper con presupuesto diario

Este ejemplo usa Token Count API antes de enviar, guarda el usage real en JSONL y corta si el gasto proyectado supera DAILY_BUDGET_USD.

npm init -y
npm i @anthropic-ai/sdk

// budgeted-message.mjs
import Anthropic from "@anthropic-ai/sdk";
import fs from "node:fs";

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const model = process.env.CLAUDE_MODEL ?? "claude-sonnet-4-6";
const maxTokens = Number(process.env.MAX_TOKENS ?? 700);
const dailyBudgetUsd = Number(process.env.DAILY_BUDGET_USD ?? 5);

const RATES = {
  "claude-opus-4-8": { input: 5, output: 25, cacheWrite5m: 6.25, cacheRead: 0.5 },
  "claude-sonnet-4-6": { input: 3, output: 15, cacheWrite5m: 3.75, cacheRead: 0.3 },
  "claude-haiku-4-5": { input: 1, output: 5, cacheWrite5m: 1.25, cacheRead: 0.1 },
};

function usdFromUsage(usage, rate) {
  return (
    (usage.input_tokens ?? 0) * rate.input +
    (usage.output_tokens ?? 0) * rate.output +
    (usage.cache_creation_input_tokens ?? 0) * rate.cacheWrite5m +
    (usage.cache_read_input_tokens ?? 0) * rate.cacheRead
  ) / 1_000_000;
}

function todayTotalUsd(path) {
  if (!fs.existsSync(path)) return 0;
  const today = new Date().toISOString().slice(0, 10);
  return fs.readFileSync(path, "utf8")
    .trim()
    .split("\n")
    .filter(Boolean)
    .map((line) => JSON.parse(line))
    .filter((row) => row.date === today)
    .reduce((sum, row) => sum + row.usd, 0);
}

const messages = [
  { role: "user", content: "List only the top three bug risks in this TypeScript function." },
];

const rate = RATES[model];
if (!rate) throw new Error(`No rate table for ${model}`);

const counted = await anthropic.messages.countTokens({ model, messages });
const worstCaseUsd = (counted.input_tokens * rate.input + maxTokens * rate.output) / 1_000_000;
const logPath = "claude-usage.jsonl";

if (todayTotalUsd(logPath) + worstCaseUsd > dailyBudgetUsd) {
  throw new Error(`Budget stop: projected daily spend exceeds $${dailyBudgetUsd}`);
}

const response = await anthropic.messages.create({
  model,
  max_tokens: maxTokens,
  cache_control: { type: "ephemeral" },
  system: "You are a concise senior code reviewer. Return only actionable findings.",
  messages,
});

const usd = usdFromUsage(response.usage, rate);
fs.appendFileSync(logPath, JSON.stringify({
  date: new Date().toISOString().slice(0, 10),
  model,
  usd: Number(usd.toFixed(6)),
  usage: response.usage,
}) + "\n");

console.log({ id: response.id, usd: Number(usd.toFixed(6)), usage: response.usage });

ANTHROPIC_API_KEY=sk-ant-...
DAILY_BUDGET_USD=5 node budgeted-message.mjs

Para explicarlo a alguien nuevo: pesa la solicitud, guarda el recibo y se detiene antes de superar el presupuesto del día.

Ejemplo 3: reporte diario de equipo

Las organizaciones pueden consultar uso diario con Admin Usage and Cost API. Requiere una Admin API key y no está disponible para cuentas individuales.

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-06-01T00:00:00Z&\
ending_at=2026-06-08T00:00:00Z&\
group_by[]=model&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

Señal	Riesgo	Acción
Uso de Opus	Tareas simples usan el modelo premium	Enruta resúmenes, traducciones y formato a Sonnet/Haiku
Tokens de salida	Las respuestas son demasiado largas	Limita hallazgos, líneas y max_tokens
Lecturas de caché	cache_read_input_tokens está cerca de cero	Quita timestamps y valores aleatorios del prefijo cacheado

Tres casos de uso

Desarrollador individual: usa Sonnet por defecto, reserva Opus para arquitectura o debugging difícil y limpia el contexto cuando cambia la tarea.

Contenido y localización: cachea la guía de estilo y cambia solo el cuerpo del artículo. Para trabajos grandes y asíncronos, evalúa el descuento de 50% de Batch API.

Formación y equipos: los días de capacitación generan concurrencia inusual. Define presupuesto diario, umbrales y reglas de prompts antes de empezar. Para programas de adopción de equipo, revisa /training/.

Errores comunes

Una API key cambia la facturación. La ayuda oficial indica que ANTHROPIC_API_KEY tiene prioridad sobre la suscripción iniciada en Claude Code. Usa /status y elimina la variable si quieres usar la cuota incluida.

No medir el cache. El prompt cache requiere un prefijo estable. Un timestamp en el system prompt puede destruir la tasa de acierto.

Dejar la salida abierta. Una review debe tener máximo de hallazgos; un resumen, longitud máxima; una generación de código, alcance claro.

Copiar precios antiguos. Los modelos y precios cambian. Revisa la página oficial antes de publicar calculadoras o presupuestos.

Usar proxies baratos sin auditoría. Si no puedes verificar modelo, retención de logs y manejo de credenciales, el descuento no es ahorro real.

Lecturas relacionadas

• Claude Code token optimization
• Claude Code pricing guide
• Claude Code context management
• Claude Code permission budget loop

Plantillas, hojas de cálculo y checklists de control de costos están en /products/.

Resultado práctico

En las pruebas de ClaudeCodeLab, el mayor impacto vino de controles sencillos: cachear instrucciones comunes, enviar traducción y formato a Haiku/Sonnet, reservar Opus para decisiones difíciles y registrar cada usage en JSONL. Empieza con alerta al 80%, bloqueo al 100% y limpieza de contexto al cambiar de tarea.