Límites

Rate limits

Dos presupuestos separados, ambos por empresa:

Superficie	Límite
Facturación por API key (/api/v1/billing/* con X-Api-Key)	60 llamadas/min
MCP y tools de agente (POST /api/v1/mcp, keys agent:read / OAuth)	120 llamadas/min

Al superar un límite, la API responde 429 con el header Retry-After. Los dos presupuestos no se mezclan: tu backend de emisión no compite con tus agentes conectados por MCP.

Dos detalles del presupuesto por key que importan en integraciones reales:

• El límite es por empresa, no por key: todas las keys de una misma empresa comparten los 60/min. Si corres N sistemas con N keys, se reparten el mismo presupuesto.
• Payload máximo 2 MiB en POST /billing/dte (~1 MiB en las demás rutas). Sobre el límite la API responde 413 con el sobre JSON estándar (code: PAYLOAD_TOO_LARGE) — reduce el tamaño del documento (menos líneas de detalle o glosas más cortas) y reintenta. Verificado en vivo: hasta 2026-09 esto era un 502 con página HTML del CDN; ya no.

Cómo manejarlo

• El SDK reintenta los 429 automáticamente con backoff exponencial y jitter, respetando el header Retry-After. Si el límite persiste, recibes un RateLimitError con retryAfter:

  import { RateLimitError } from '@simplohq/sdk';
  
  try {
    await simplo.dtes.list();
  } catch (error) {
    if (error instanceof RateLimitError) {
      console.error(`Rate limit. Reintenta en ${error.retryAfter ?? '?'}s`);
    }
  }

• El trabajo por lotes debe marcar su propio ritmo en vez de depender de los reintentos: encola y espacia las llamadas — con 60/min por empresa, un lote grande de emisiones necesita ritmo propio.

• Los agentes conectados por MCP tienen su propio presupuesto (120/min) — no compiten con tu backend de emisión.

Límites de paginación

limit en los listados va de 1 a 100 items por página (default 20) — ver Paginación.

Relacionado

• Errores — RateLimitError y las reglas de reintento