Límites y errores

Formato de los errores

Todo error tiene el mismo formato:

{ "error": "invalid_token", "message": "Texto explicativo em português" }

• error es un código estable, en snake_case. Use este campo en su código.
• message es un texto para personas y puede cambiar. Viene en portugués.

Códigos de estado

Estado	Significado
400	Datos de la solicitud inválidos (validation_error, invalid_json, invalid_phone y los códigos de multimedia)
401	Token de la instancia o token de seguridad de la cuenta ausente o inválido
402	Instancia suspendida o con pago pendiente
403	IP no autorizada o cuenta bloqueada
404	Recurso no encontrado, como una entrega de webhook o una ruta que no existe
409	Operación incompatible con el estado actual de la instancia
413	Cuerpo de la solicitud demasiado grande
415	Tipo de contenido no aceptado: envíe application/json
422	Contacto dado de baja
429	Demasiadas solicitudes
500	Error interno (internal_error)

Los códigos de cada ruta están en las tablas de errores de las guías de autenticación, conexión, envío de mensajes y envío de multimedia.

En validation_error, el message lista los campos con problemas, como Dados inválidos: to, text.

Límite de solicitudes

Hay un límite de solicitudes por minuto por IP (hoy, 300) y por instancia (hoy, 600). Al superarlo, la API responde 429 con el código rate_limited y el encabezado Retry-After, que trae los segundos que debe esperar antes de volver a intentar.

Los fallos de autenticación seguidos desde la misma IP también llevan a 429: tras muchos 401 en un minuto, las llamadas de esa IP se rechazan hasta que pase la ventana.

const resposta = await fetch(url, opcoes)
if (resposta.status === 429) {
  const segundos = Number(resposta.headers.get('retry-after') ?? 1)
  await new Promise((r) => setTimeout(r, segundos * 1000))
  // vuelva a intentar
}

El envío de mensajes también pasa por una cola con ritmo controlado, para proteger el número. Por eso el 202 no significa envío inmediato.

Tamaños

Elemento	Límite
Texto de un mensaje	10.000 caracteres
Leyenda de multimedia	1.024 caracteres
Multimedia en base64 (decodificada)	16 MB
Cuerpo de una solicitud de multimedia	25 MB
Cuerpo de las demás solicitudes	1 MB
Teléfonos en POST /contacts/check	50 por llamada

Salud del número

GET /v1/instances/{instanceId}/health muestra los contadores de envío y recepción de la instancia, para que usted note a tiempo si el número está enviando demasiado. La respuesta trae today y last7Days (cada uno con sent y received), byType y warning, que vale "high_send_ratio" cuando el volumen enviado es desproporcionado respecto al recibido, o null.

Buenas prácticas

• Haga las llamadas desde su servidor y guarde el token en una variable de entorno.
• Ante un 429, espere el tiempo de Retry-After en lugar de reintentar en un bucle.
• No repita un envío solo porque no vio el webhook: consulte GET /queue y el historial de entregas antes.
• Respete la baja. Quien pide salir y sigue recibiendo mensajes suele denunciar el número.