Límites y errores
Cuántas llamadas puedes hacer por día y por minuto, qué hacer ante cada 429 y los errores que comparte toda la API.
Lo que vale para toda la API, con cualquier llamada. Cada límite responde 429 con su código en error: según cuál sea, esperas y reintentas, o reintentar no sirve.
Por día
- Cada clave puede hacer hasta 10 000 llamadas por día en el área de tus números y tu cuenta (también los webhooks y las alertas) y otras 10 000 en la de grupos (también las campañas, los envíos programados y las estadísticas). Cada una cuenta aparte.
- La de contactos y mensajes (todo lo demás) no tiene tope diario.
- El tope se reinicia todos los días a las 00:00 UTC.
- Al pasarlo, la API responde
429 daily_cap_exceededcon la cabeceraRetry-After: los segundos que faltan para las 00:00 UTC. Hasta entonces no repitas las llamadas de esa área; las de las otras siguen funcionando.
Por minuto
- Además, cada área limita cuántas llamadas por minuto se pueden hacer, por grupo de llamadas. Cada grupo cuenta aparte.
- Según la llamada, ese cupo se cuenta:
- por usuario: lo comparten todas las claves de tu usuario de Funnelchat y lo que haces en el panel, así que el panel puede gastar el cupo de tu integración, y al revés;
- por workspace: lo comparten todas las claves y todos los usuarios del workspace de la clave; cada workspace de tu cuenta tiene el suyo, y lo que pasa en otro no lo gasta;
- por clave: cada clave tiene el suyo, aparte del panel y de tus otras claves;
- por número: lo comparten todas las claves y el panel para ese número.
- Si tu cuenta usa workspaces separados, el cupo por usuario también se cuenta en cada workspace: un usuario tiene el suyo en cada workspace en el que trabaja.
- Al pasarlo,
429 rate_limitedconRetry-After: espera esos segundos y reintenta. Reparte las llamadas en el tiempo en lugar de mandarlas todas juntas.
| Área | Por minuto |
|---|---|
| Tus números y tu cuenta (también los webhooks y las alertas) | La mayoría de las llamadas, 200 por workspace. Crear un número, reiniciar su sesión, anular un link de alta y crear o probar un webhook: 10 por clave entre todas; crear un link de alta, otros 10 por clave. Ver, editar y borrar un webhook y ver sus entregas: 60 por clave. Pedirle a Meta la salud de un número: 6 por número. Ver tu cuenta y las alertas no tienen un límite por minuto propio. La referencia de cada llamada dice el suyo. |
| Grupos (también las campañas, los envíos programados y las estadísticas) | Todo se cuenta por usuario: hasta 600 entre todas las llamadas. Algunas tienen además su propio tope: 30 entre crear un grupo, sus acciones y mandarle un mensaje; 30 para importar un grupo; 30 para leer en el momento su link de invitación o sus solicitudes; 60 para ver el resultado de una acción. Varias lecturas (los planes de una campaña, la actividad de los participantes, los grupos y canales de un número, los envíos programados y sus resultados): 60, en un contador que comparten con pantallas del panel. |
| Contactos y mensajes (todo lo demás) | Escrituras: 30 por usuario; algunas más delicadas (borrar contactos o campos, cancelar una difusión, mover o sacar contactos en bloque de un tablero, traer una plantilla de Meta): 10 por usuario. Varias lecturas (etiquetas, campos, flujos, ventas, puntaje): 120 por usuario. Listar contactos, conversaciones y mensajes no tiene límite por minuto. Formularios de WhatsApp: 120 lecturas y 60 cambios por clave, y 30 por workspace en lo que pasa por Meta. Marcar todas las conversaciones como leídas o no leídas: 5 por workspace. |
- Los envíos de mensajes no tienen un límite por minuto: los limita el ritmo del número por el que salen, que responde el mismo
429 rate_limitedconRetry-After(ver Mandar mensajes).
Contactos activos
- Cuando tu cuenta llega a su límite de contactos activos, un envío puede responder
429conmac_lockout_24homac_limit_reached. - Si tu cuenta usa workspaces separados, cada workspace tiene su propio plan y su propio límite, y se cuenta el del workspace del número por el que envías.
- El envío frenado no sale y no se guarda: no queda ningún mensaje en el historial del contacto, tampoco tu
client_reference. - No trae
Retry-Aftery reintentar no sirve hasta que cambie el límite: al sumar capacidad o al empezar un ciclo nuevo con cupo. Cuánto te queda lo ves en Tu cuenta y tu equipo.
Errores
Cuando la API rechaza una llamada, el cuerpo trae error, un código que no cambia, y message, un texto para personas; un 422 trae además errors, con lo que está mal en cada dato. Decide por el código HTTP y por error, nunca por message.
| Código | error | Qué pasó | Qué hacer |
|---|---|---|---|
401 | unauthenticated | Falta la clave, no existe o fue revocada. | Revisa la cabecera Authorization y que la clave siga activa. |
402 | payment_required | El pago de tu cuenta o de tu workspace está vencido (cada workspace con facturación propia tiene el suyo). Solo lo responden las llamadas que lo indican en la referencia. En las acciones de grupo, 402 plan_cap_reached es otra cosa: el plan no incluye la acción o llegó a su tope (al crear un grupo, el tope de grupos oficiales de tu plan). | Regulariza el pago en el panel de Funnelchat: hasta entonces, reintentar no sirve. Con plan_cap_reached, tampoco: hace falta otro plan. |
403 | permission_denied | A tu clave le falta la casilla que pide la llamada. | Crea una clave con esa casilla marcada: la referencia de cada llamada dice cuál. |
403 | route_not_available | La llamada no está abierta a claves. | Ningún permiso la habilita. |
403 | workspace_archived | El workspace de tu clave está archivado. Cada área lo escribe a su manera: conversations, WORKSPACE_ARCHIVED (toda llamada); accounts, WORKSPACE_INACTIVE con inactive_reason: archived (las rutas que cortan por pago, en lugar del 402); communities, workspace_archived (las operaciones que necesitan el plan activo). | Se reactiva desde el panel: hasta entonces, reintentar no sirve. |
404 | not_found | Lo que pediste no existe, es de otra cuenta o es de otro workspace de tu cuenta: todo responde igual. Un número de otra cuenta o de otro workspace de la tuya responde este 404 antes que cualquier otro error, aunque el pago esté vencido o a tu clave le falte un permiso. Algunas llamadas usan un código propio, como group_not_found. | Revisa el id. |
422 | El de la llamada | Un dato no es válido o una regla no deja hacer lo que pediste. Los códigos de cada llamada están en su página de la referencia. | Corrige lo que dicen errors o el código. |
429 | daily_cap_exceeded, rate_limited, mac_lockout_24h o mac_limit_reached | Llegaste a uno de los límites de arriba. | Si trae Retry-After, espera esos segundos; si no, no reintentes. |
500 | internal_error; en los envíos de mensajes, también gate_misconfigured | Falló algo de nuestro lado, no tu llamada. | Reintenta más tarde. En un envío, antes busca el mensaje por tu client_reference: puede haber quedado registrado. |
Funciones de Funnelchat
Lo que haces con Funnelchat después del primer uso —tus contactos, etiquetas, tableros, tickets, automatizaciones, difusiones, campañas de grupos, ventas y tu cuenta—.
Identificadores
Cómo son los ids de la API (texto con un prefijo que dice el tipo), la tabla de prefijos y qué pasa con un id inválido.