Límites de uso

Los topes

• La API y el servidor MCP comparten la cuenta de pedidos: el mismo token gasta de la misma cuota por los dos lados.
• La ventana es de un minuto de reloj. Cuando termina, el contador vuelve a cero.
• Los pedidos rechazados por el límite también cuentan: insistir sin esperar alarga el bloqueo.

Encabezados de cuota

Toda respuesta de la API y del MCP a un pedido con un token válido dice cuánto queda. No los traen el 401 de un token que no pasa, el 403 con el código no_activo de una cuenta que no está activa o no tiene la API, ni /v1/openapi.json, que se pide sin token:

Si el token y la cuenta están los dos cerca del tope, los encabezados muestran el más ajustado de los dos.

HTTP/1.1 200 OK
RateLimit-Limit: 120
RateLimit-Remaining: 117
RateLimit-Reset: 42
x-kaptativa-pedido: ped_3f9a1c0b7d2e4f6a8b1c2d3e4f5a6b7c

Cuando te pasás

La API responde 429 con el código limite y no ejecuta el pedido. El mensaje dice qué tope se pasó: el del token o el de la cuenta («La cuenta pasó los 600 pedidos por minuto entre todos sus tokens. Esperá un momento.»), y RateLimit-Limit trae ese tope.

HTTP/1.1 429 Too Many Requests
Retry-After: 18
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 18

{
  "error": {
    "codigo": "limite",
    "mensaje": "Pasaste los 120 pedidos por minuto de este token. Esperá un momento.",
    "pedido": "ped_5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d"
  }
}

Esperá los segundos de Retry-After y repetí. Si el pedido cambia algo, con la misma clave de idempotencia.

async function pedir(direccion, opciones) {
  for (;;) {
    const respuesta = await fetch(direccion, opciones);
    if (respuesta.status !== 429) return respuesta;
    const segundos = Number(respuesta.headers.get("retry-after")) || 5;
    await new Promise((listo) => setTimeout(listo, segundos * 1000));
  }
}

Para no llegar al tope

• Pedí páginas grandes: con limite=100 una lista larga cuesta menos pedidos. Mirá Paginación.
• No consultes cada tanto para ver si algo cambió: suscribite al evento con un webhook.
• Si corrés procesos en paralelo con el mismo token, mirá RateLimit-Remaining y frená antes de llegar a cero.
• Guardá de tu lado lo que no cambia seguido, como la lista de operaciones.