Cuotas y límites de frecuencia

Dos cosas distintas limitan lo que puedes hacer: cuántas búsquedas al día permite tu plan y a qué ritmo pueden llegar las solicitudes. Ambas se indican en cada respuesta, así que un cliente puede regular su ritmo sin tener que provocar un error para averiguar dónde están los límites.

Límite de frecuencia: diez solicitudes por minuto

El límite es por cuenta y lo comparten la API y el servidor MCP: diez llamadas por minuto, lleguen por donde lleguen. Una undécima solicitud dentro del intervalo se responde de inmediato con 429 too_many_requests y un encabezado Retry-After que indica los segundos que faltan para que se libere un hueco. El mismo número aparece en el cuerpo como error.retry_after.

HTTP/2 429
Retry-After: 18

{ "error": { "code": "too_many_requests",
             "message": "At most 10 requests per minute.",
             "retry_after": 18 } }

Espera los segundos de Retry-After y repite la solicitud. No se consumió nada ni se gastó cuota.

La API nunca mantiene una conexión abierta para frenarte. Las antiguas URL de exportación sí lo hacen (esperan de segundo en segundo hasta medio minuto antes de rechazar la solicitud), y ese es uno de los motivos por los que existe la API.

Cuota diaria

Tu plan permite un número de búsquedas al día y un número de solicitudes con fragmentos al día, que se cuentan por separado. Ambas se restablecen a la siguiente medianoche UTC, no 24 horas después de usarlas.

Una búsqueda descuenta una de la cuota de búsquedas.
Una búsqueda con snippets=1 descuenta una de la cuota de fragmentos en su lugar.
/v1/account no cuesta nada.

Cuando se agota una cuota, la solicitud se rechaza con 429 quota_exceeded o 429 snippet_quota_exceeded, indicando el límite, lo que se ha usado y cuánto falta para el restablecimiento. Agotar la cuota de fragmentos no impide hacer búsquedas normales.

Profundidad de los resultados

Un plan también determina hasta qué punto del ranking se muestran los resultados: disclosed_positions en /v1/account. Las filas que quedan más allá de ese punto se omiten en lugar de dejarse en blanco y, cuando se omite alguna, truncated es true en el cuerpo y X-Truncated: true en los encabezados.

Esta es la diferencia más importante entre la API y el sitio web. Un navegador que ha agotado su cuota pasa discretamente a la profundidad del plan gratuito y muestra menos, lo cual está bien para una persona que mira una página. Un script no puede darse cuenta, así que la API rechaza la solicitud en lugar de recortarla.

Consultar el estado actual

Cada respuesta autenticada incluye cinco encabezados:

Encabezado	Significado
`X-RateLimit-Limit`	Búsquedas permitidas hoy.
`X-RateLimit-Remaining`	Búsquedas que quedan hoy.
`X-RateLimit-Reset`	Hora Unix en que se restablece la cuota del día.
`X-Snippets-Limit`	Solicitudes con fragmentos permitidas hoy.
`X-Snippets-Remaining`	Solicitudes con fragmentos que quedan hoy.

Los resultados incluyen tres más:

Encabezado	Significado
`X-Total-Results`	Cuántos sitios coinciden en todo el índice.
`X-Returned-Results`	Cuántas filas contiene esta respuesta.
`X-Truncated`	`true` si el límite de profundidad del plan eliminó filas.

Estadísticas de uso

/v1/account da el panorama completo en una sola llamada, y no consume nada:

curl -H "Authorization: Bearer $KEY" https://api.publicwww.com/v1/account

{
  "plan": "enterprise",
  "plan_until": 1819461840,
  "full_access": true,
  "quota": {
    "searches": { "limit": 300, "used": 12, "resets_at": 1787961600 },
    "snippets": { "limit": 100, "used": 3,  "resets_at": 1787961600 }
  },
  "limits": {
    "disclosed_positions": 4294967295,
    "disclosed_positions_snippets": 4294967295,
    "max_per_page": 1000000,
    "max_per_page_snippets": 10000
  }
}

La antigua https://publicwww.com/profile/api_status.xml?key=... devuelve los mismos contadores en XML y sigue funcionando. Pertenece a las antiguas URL; el código nuevo debería usar /v1/account, que además indica los límites, no solo los recuentos.

Siguiente Errores