Erros e limites

A API usa os códigos HTTP padrão. Erros trazem uma mensagem em JSON.

Código	Significado	Quando acontece
200	OK	Requisição bem-sucedida
201	Created	Recurso criado (ex.: lead, tarefa, assinatura)
401	Unauthorized	Chave ausente, inválida ou expirada
403	Forbidden	Conta inativa ou chave sem permissão para a operação
422	Unprocessable Entity	Validação ou regra de negócio (campos inválidos, etapa bloqueada, limite de plano, janela do WhatsApp)
429	Too Many Requests	Limite de requisições por minuto excedido
502	Bad Gateway	Falha do provedor externo (ex.: envio de WhatsApp)

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

As mensagens possíveis são: API Key não fornecida., API Key inválida. e API Key expirada.

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

Quando a conta está suspensa: { "message": "Conta inativa." }.

Erro de validação (campos):

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

Regra de negócio. Exemplos:

• Etapa bloqueada (há tarefas obrigatórias pendentes na etapa atual):

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

• Limite do plano atingido:

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

• Janela de 24h do WhatsApp fechada (somente 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
}

Retornado quando o provedor de WhatsApp recusa o envio:

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

• 60 requisições por minuto, por API Key.
• Ao exceder, a API responde 429 com o header Retry-After (em segundos) e o campo retry_after no corpo.
• O limite é por chave (independe do IP).

Listagens (GET /leads, GET /tasks) aceitam:

• page — página (padrão 1).
• per_page — itens por página (padrão 50, máximo 200).

E retornam um objeto meta:

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

Dica para sincronização: use o filtro updated_since em GET /leads para buscar apenas os leads alterados desde a última consulta.

• Respostas trazem success: true|false.
• Datas em ISO 8601.
• O parâmetro ?include= (em Leads) carrega relações extras sob demanda; tokens desconhecidos são ignorados (não geram erro).