Solución de problemas

Códigos de error HTTP

Código	Significado	Qué revisar
401 Unauthorized	Falta el JWT o la API Key, o venció	Revisá el header Authorization: Bearer o x-api-key
403 Forbidden	Autenticado, pero sin permiso para esa acción	Puede ser un límite de plan (ver Suscripciones) o un recurso que no te pertenece
404 Not Found	El recurso no existe, o no es tuyo	Los IDs de otro usuario devuelven 404, no 403 — no se distingue “no existe” de “no es tuyo” por diseño
429 Too Many Requests	Superaste el rate-limit del endpoint	Ver Límites y cuotas
400 Bad Request	Body inválido	El mensaje de error detalla el campo — la API usa validación estricta y rechaza campos no declarados en el DTO

“Mi sesión nunca pasa a connected”

• Si estás usando QR: el código expira solo a los pocos segundos — seguí pidiendo GET /sessions/:id/qr hasta obtener uno fresco y escaneá rápido.
• Si estás usando pairing code: el código vence en ~60s, volvé a pedirlo con POST /sessions/:id/pairing-code.
• Confirmá que el teléfono que estás vinculando tenga WhatsApp actualizado y conexión a internet estable.

“Un schedule que programé nunca se envió”

No es necesariamente un error — antes de descartarlo como falla:

1. ¿La sesión sigue connected? Revisá GET /sessions/:id.
2. ¿Hay una pausa anti-baneo activa? GET /sessions/:id/health muestra pause con el motivo — si está pausada, el mensaje se reprograma solo, no se pierde.
3. ¿El número existe en WhatsApp? Si no, el schedule pasa a failed con el motivo en el campo error (no reintenta).

“Quiero enviar a muchos contactos ya mismo y no puedo”

Es intencional. La API aplica cuotas y demoras para no arriesgar el número vinculado — no hay forma de saltear esto vía configuración de tu integración. Ver Envío masivo seguro para entender los tiempos esperados según el tamaño de tu lista.

“No puedo crear una API Key”

Las API Keys requieren plan Pro. POST /auth/api-keys devuelve 403 Forbidden con el mensaje "API Keys are only available on the Pro plan" si tu cuenta está en Free — contactá al administrador de tu instancia para actualizar el plan.