En esta sección
Guías / Límites y cuotas

Límites y cuotas

Límite diario de peticiones por workspace, rate limit por key, cabeceras, cuota mensual de los planes Developer y Tech Partner, y qué hacer con cada 429.

Actualizada el Ver .md

La API de Meteor aplica dos límites a todo el tráfico que llega con API key:

Los dos se ven en cada respuesta, así que no tienes que adivinar cuánto te queda. Además, los planes Developer y Tech Partner tienen una cuota mensual por key, las keys met_test_ un tope diario de runs de prueba y cualquier key puede llevar un presupuesto de Energía.

Límite diario de peticiones por workspace

Cada plan incluye un número de peticiones por día para todo el workspace. Se suman todas las keys del workspace, así que crear otra key no te da más cupo.

Qué cuenta: toda petición autenticada con una API key, llegue por la API, el SDK, la CLI o el servidor MCP. En el MCP, cada POST /mcp cuenta como una petición, aunque adentro llame a varias herramientas. Lo que haces desde el panel de Meteor con tu sesión no cuenta.

Qué es un día: el día UTC. El contador vuelve a cero a las 00:00 UTC, que en Colombia son las 7:00 p. m.

PlanPeticiones al día
Developer y Tech Partner3.500
Estudio3.500
Oficina10.000
Edificio17.000
Ciudadela35.000
Campus100.000

Cabeceras del límite diario

Toda respuesta a una petición con API key trae el estado del día:

CabeceraQué dice
X-Daily-LimitTu límite del día: el de tu plan más los complementos que tengas.
X-Daily-RemainingCuántas peticiones te quedan hoy. Llega a 0 cuando pasas el límite.
X-Daily-ResetSegundos que faltan para que el contador vuelva a cero (00:00 UTC).
curl -i https://api.met.meteor.com.co/api/v1/contacts \
  -H "Authorization: Bearer met_live_tu_key"
# ...
# HTTP/2 200
# x-daily-limit: 10000
# x-daily-remaining: 3120
# x-daily-reset: 18230

El conteo se actualiza cada minuto, así que X-Daily-Remaining puede ir unos segundos por detrás de tu tráfico real.

Qué pasa cuando llegas al límite

{
  "error": {
    "type": "rate_limit_error",
    "code": "daily_request_limit_exceeded",
    "message": "Tu workspace superó el límite diario de peticiones."
  }
}

Decide por code, no por el texto de message. A diferencia de rate_limited, este 429 no se resuelve reintentando en unos segundos: el Retry-After puede ser de horas. Desde @meteor.ia/sdk 0.9.0 y meteor-ia 0.3.0, los SDKs oficiales no lo reintentan: te entregan el error de una vez, con retryAfter (retry_after en Python) e isQuota (is_quota) en true; si tu integración corre trabajos por lotes, mira X-Daily-Remaining y frena antes de llegar ahí.

Cómo ampliarlo

Si te quedas corto, tienes dos caminos:

Cómo consultarlo

GET /billing/limits devuelve todos los límites de tu plan con lo que llevas usado, y necesita el scope billing:read. El límite diario de peticiones es el recurso api_requests_daily:

{
  "object": "plan_limits",
  "plan": { "slug": "oficina", "name": "Oficina", "price_monthly_usd": 299 },
  "resources": [
    {
      "key": "api_requests_daily",
      "label": "Peticiones de API",
      "period": "day",
      "used": 6880,
      "included": 10000,
      "extra": 0,
      "limit": 10000,
      "unlimited": false,
      "enforcement": "soft",
      "resets_at": "2026-09-26T00:00:00Z",
      "addons": [
        { "slug": "api_daily_1000", "grants": 1000, "price_usd": 15, "owned_quantity": 0 },
        { "slug": "api_daily_10000", "grants": 10000, "price_usd": 90, "owned_quantity": 0 }
      ]
    }
  ]
}

limit es included más extra (lo que suman tus complementos). enforcement dice cómo se aplica cada recurso: hard bloquea al llegar, soft avisa al 100 % y frena al triple, y none no frena. Un recurso sin tope trae unlimited: true y limit: null. La misma respuesta trae los demás recursos del plan (miembros, contactos, tareas al día, números de WhatsApp y cuentas de Meta), cada uno con sus complementos.

Rate limit por key (peticiones por minuto)

Cada key tiene su propio presupuesto de peticiones por minuto, aparte del resto del tráfico de tu workspace. El valor por defecto es 300 peticiones por minuto.

Tu plan no sube ese número: solo puede fijar uno más bajo. Hoy lo hacen los planes Developer y Tech Partner, que dejan cada key en 60 por minuto. Los demás planes usan el valor por defecto. Si una key tiene además un límite propio, rige el menor de los dos.

El límite se cuenta por key (no por IP ni por workspace), así que dos keys del mismo workspace no compiten por el ritmo. El límite diario, en cambio, sí es uno solo para todas.

Cabeceras del rate limit

CabeceraQué dice
X-RateLimit-LimitEl tope de peticiones de la ventana actual (refleja el límite de tu key).
X-RateLimit-RemainingCuántas peticiones te quedan en la ventana.
X-RateLimit-ResetSegundos hasta que la ventana se reinicia.
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 una cabecera 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 este 429 a mano. Si integras la API directamente, espera los segundos que indica Retry-After antes de reintentar.

Los límites se resuelven con el plan activo del workspace cada vez que usas la key, aunque la hayas creado antes de contratar el plan.

Cuota mensual (planes Developer y Tech Partner)

Los planes Developer y Tech Partner tienen además una cuota mensual por key: cada key lleva su propio contador del mes. Al superarla, la API responde 429 con code: "quota_exceeded" hasta que empiece el mes siguiente. Los demás planes no tienen cuota mensual; su techo es el límite diario del workspace.

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 petición buscable por request_id.

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 resto de los límites. 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 peticiones, 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

← AnteriorErrores, idempotencia y paginación