Telm mide la API de dos formas: un límite de tasa por minuto (un techo de ráfaga) y una cuota diaria (tu presupuesto total para el día UTC). Ambos escalan con el plan. Cada respuesta medida devuelve X-Quota-Limit, X-Quota-Used y X-Quota-Reset para que siempre conozcas tu presupuesto restante, y ambos límites devuelven 429 con un encabezado Retry-After cuando se superan.
1Dos límites: tasa por minuto y cuota diaria
Hay dos techos separados. El límite de tasa por minuto limita cuántas peticiones puedes hacer dentro de un solo minuto, suavizando las ráfagas. La cuota diaria es tu presupuesto general: limita cuántas llamadas medidas puedes hacer a lo largo de todo el día UTC.
Son independientes. Puedes alcanzar el límite por minuto teniendo aún mucha cuota diaria restante (simplemente estás enviando demasiado rápido), o agotar tu cuota diaria estando muy por debajo del límite por minuto (has consumido el día). Ambos devuelven un estado 429, pero por razones distintas: comprueba el código de error en el cuerpo para distinguirlos.
- Límite de tasa por minuto — un techo de ráfaga, se reinicia cada minuto.
- Cuota diaria — tus llamadas medidas totales del día, se reinicia a medianoche UTC.
- La cuota se cuenta una vez por cuenta, compartida entre todas tus claves.
2Cuota diaria por plan
Tu cuota diaria es el número de llamadas medidas a la API que puedes hacer por día UTC, y depende de tu plan. El contador se comparte entre todas tus claves y sigue el mejor plan entre los grupos que administras; sin una suscripción de pago, estás en el nivel Free.
La ventana es el día calendario UTC, así que tu contador de uso se reinicia a cero a medianoche UTC. Una comprobación de spam por lotes cuesta una llamada por elemento del lote, no una llamada por toda la petición.
- Free — 100 llamadas al día.
- Basic — 1,000 llamadas al día.
- Pro — 10,000 llamadas al día.
- Business — 50,000 llamadas al día.
3Límite de tasa por minuto por plan
Además de la cuota diaria, cada clave de API está limitada a un número de peticiones por minuto según su nivel de plan. Este es un límite de suavizado: impide que un solo cliente envíe un pico enorme en un segundo, incluso cuando el presupuesto diario está lejos de gastarse.
Por separado, techos amplios por IP y por cuenta aplican a toda la API para mantener la plataforma estable. En el uso normal (peticiones constantes y acompasadas) nunca los tocarás; solo se activan ante ráfagas abusivas.
- Free y Basic — 60 peticiones por minuto.
- Pro — 600 peticiones por minuto.
- Business — 1,800 peticiones por minuto.
- Reparte las peticiones en lugar de dispararlas todas a la vez.
4Leer tu presupuesto restante
Nunca tienes que adivinar cuánta cuota queda. Cada respuesta medida (éxito o fallo) incluye tres encabezados: X-Quota-Limit (tu límite diario), X-Quota-Used (cuántas llamadas has gastado hoy), y X-Quota-Reset (el momento, en UTC, en que el contador se reinicia).
Los endpoints de comprobación de spam también reflejan los mismos números dentro del cuerpo de la respuesta bajo un objeto quota, así que puedes leer tu presupuesto restante sin analizar los encabezados. Úsalos para acompasar tus propias peticiones y para avisarte antes de quedarte sin cuota.
- X-Quota-Limit — tu límite diario de llamadas.
- X-Quota-Used — llamadas gastadas hasta ahora hoy.
- X-Quota-Reset — hora de reinicio en UTC (RFC 3339).
- Las respuestas de comprobación de spam también incluyen un objeto quota con los mismos campos.
5Qué pasa ante un 429
Cuando cruzas cualquiera de los límites, la API devuelve HTTP 429 con un encabezado Retry-After que te dice cuántos segundos esperar. Para el límite de tasa por minuto, Retry-After es alrededor de un minuto. Para la cuota diaria, el cuerpo lleva un código daily_quota_exceeded más tu plan, límite, contador de uso, la hora de reinicio, y una pista de mejora, y Retry-After cuenta hacia atrás hasta la medianoche UTC.
La forma correcta de manejar un 429 es retroceder y reintentar tras el retraso de Retry-After, no machacar el endpoint. Los clientes bien educados leen el encabezado y pausan; los clientes que siguen reintentando de inmediato simplemente permanecen bloqueados.
- 429 rate_limit_exceeded — enviaste demasiado rápido; espera alrededor de un minuto.
- 429 daily_quota_exceeded — el día está consumido; espera hasta el reinicio UTC o mejora el plan.
- Respeta siempre el encabezado Retry-After antes de reintentar.