Errores y límites

La API usa los códigos HTTP estándar. Los errores devuelven un mensaje en JSON.

Código	Significado	Cuándo ocurre
200	OK	Solicitud exitosa
201	Created	Recurso creado (ej.: lead, tarea, suscripción)
401	Unauthorized	Clave ausente, inválida o expirada
403	Forbidden	Cuenta inactiva o clave sin permiso para la operación
422	Unprocessable Entity	Validación o regla de negocio (campos inválidos, etapa bloqueada, límite del plan, ventana de WhatsApp)
429	Too Many Requests	Límite de solicitudes por minuto excedido
502	Bad Gateway	Fallo del proveedor externo (ej.: envío de WhatsApp)

{
  "message": "API Key inválida."
}

Los mensajes posibles son: API Key não fornecida., API Key inválida. y API Key expirada.

{
  "message": "API Key sem permissão para esta operação.",
  "required_permission": "leads:write"
}

Cuando la cuenta está suspendida: { "message": "Conta inativa." }.

Error de validación (campos):

{
  "message": "The name field is required.",
  "errors": {
    "name": ["The name field is required."]
  }
}

Regla de negocio. Ejemplos:

• Etapa bloqueada (hay tareas obligatorias pendientes en la etapa actual):

{
  "success": false,
  "blocked": true,
  "message": "Complete mandatory tasks before moving the lead.",
  "pending_tasks": [
    { "id": 45, "subject": "Ligar para o cliente", "type": "call" }
  ]
}

• Límite del plan alcanzado:

{
  "success": false,
  "message": "Limite de leads do plano atingido.",
  "limit_reached": true
}

• Ventana de 24h de WhatsApp cerrada (solo API Oficial / Cloud):

{
  "success": false,
  "message": "Janela de 24h fechada — use um template.",
  "skip_reason": "window_closed"
}

{
  "message": "Rate limit excedido para esta API Key.",
  "retry_after": 35
}

Devuelto cuando el proveedor de WhatsApp rechaza el envío:

{
  "success": false,
  "message": "Falha ao enviar: ...",
  "raw": { }
}

• 60 solicitudes por minuto, por API Key.
• Al exceder, la API responde 429 con el header Retry-After (en segundos) y el campo retry_after en el cuerpo.
• El límite es por clave (independiente de la IP).

Los listados (GET /leads, GET /tasks) aceptan:

• page — página (por defecto 1).
• per_page — ítems por página (por defecto 50, máximo 200).

Y devuelven un objeto meta:

{
  "success": true,
  "data": [ ],
  "meta": {
    "total": 250,
    "per_page": 50,
    "current_page": 1,
    "last_page": 5,
    "has_more": true
  }
}

Consejo para sincronización: usa el filtro updated_since en GET /leads para obtener solo los leads modificados desde la última consulta.

• Las respuestas incluyen success: true|false.
• Fechas en ISO 8601.
• El parámetro ?include= (en Leads) carga relaciones extra bajo demanda; los tokens desconocidos se ignoran (no generan error).