Límites y cuotas

Rate limits por key, headers de rate limit, cuota mensual y cómo los SDKs reintentan solos.

La API de Meteor aplica dos tipos de límite por API key: un rate limit (cuántos requests por minuto) y una cuota (cuántos requests por mes). Ambos protegen la plataforma y son visibles en cada respuesta — no tienes que adivinar cuánto te queda.

Rate limit (requests por minuto)

Cada key tiene su propio presupuesto de requests por minuto, independiente del resto del tráfico de tu workspace. El valor por defecto es 300 requests por minuto; tu plan puede asignarle un límite mayor a la key cuando la emites.

El límite se cuenta por key (no por IP ni por workspace), así que dos keys del mismo workspace no compiten entre sí.

Headers en cada respuesta

Toda respuesta de la API pública trae el estado de tu rate limit, para que ajustes el ritmo sin llegar al bloqueo:

curl -i https://api.met.meteor.com.co/api/v1/runs \
  -H "Authorization: Bearer met_live_tu_key"
# ...
# HTTP/2 200
# x-ratelimit-limit: 300
# x-ratelimit-remaining: 99
# x-ratelimit-reset: 60

Cuando te pasas: 429 + Retry-After

Si superas el rate limit, la API responde 429 con un header Retry-After (segundos a esperar) y el cuerpo de error estándar:

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Too many requests."
  }
}

Los SDKs oficiales reintentan solos respetando el Retry-After (con backoff), así que en la mayoría de los casos no tienes que manejar el 429 a mano. Si integras la API directamente, espera los segundos que indica Retry-After antes de reintentar.

Cuota mensual

Además del rate limit por minuto, tu plan define una cuota mensual de requests. Al superarla, la API responde 429 con code: "quota_exceeded". La cuota depende de tu plan; el consumo del mes y las alertas (80% / 100%) los ves en el Workbench, en Ajustes → Desarrolladores → Actividad → Salud — ahí mismo tienes el volumen por día, la latencia p95 y cada request buscable por request_id.

Las cuotas y rate limits dependen del plan activo del workspace. Se resuelven al usar la key —aunque la hayas creado antes de contratar el plan— y se reflejan en X-RateLimit-Limit.

Tope diario de runs de prueba

Los runs que ejecutas con una key met_test_ no debitan Energía, y por eso tienen su propio tope: un máximo de runs de prueba por día y por workspace, que se cuenta aparte del rate limit y de la cuota mensual. Al alcanzarlo, POST /runs responde 429 con code: "test_run_daily_cap" y el run no se ejecuta — el tope se revisa antes de tocar el orquestador, así que no te cobran ni a medias.

{
  "error": {
    "type": "rate_limit_error",
    "code": "test_run_daily_cap",
    "message": "Se alcanzó el límite diario de runs de test de este workspace. Usa una key live o reinténtalo mañana."
  }
}

A diferencia de rate_limited, este 429 no se resuelve reintentando: el contador se reinicia al día siguiente. Tu plan puede subir el tope, y también puede dejarlo en cero (sin runs de prueba). Si te choca a diario en desarrollo, la salida es una key met_live_ —esa sí debita Energía— o un plan con más margen.

Presupuesto de Energía por key

Además de los límites de requests, cada key puede llevar un tope de gasto en dólares que asignas en Ajustes → Desarrolladores al crearla o después, sin rotarla. Con el corte automático activado, al llegar al 100 % las nuevas solicitudes se rechazan con 429 y code: "budget_exceeded" hasta el próximo mes o hasta que subas el tope; sin él, la key sigue operando y solo te avisa. En los dos casos el cruce de cada umbral (50 / 80 / 100 %) llega como evento billing.threshold si tienes un webhook suscrito con billing:read.

Es el límite que más conviene poner en una key que le entregas a un agente: acota el gasto aunque el agente se equivoque en bucle.

En resumen

• Mira X-RateLimit-Remaining para autorregularte.
• Un 429 con rate_limited es transitorio → reintenta tras Retry-After (los SDKs lo hacen solos).
• Un 429 con quota_exceeded es tu cuota del mes → sube de plan o espera al reinicio mensual.
• Un 429 con test_run_daily_cap es el tope diario de runs de prueba → espera al día siguiente o pasa a una key met_live_.
• Un 429 con budget_exceeded es el presupuesto de la key → súbelo o espera al mes siguiente.