Errors and limits

The API uses standard HTTP status codes. Errors return a JSON message.

Code	Meaning	When it happens
200	OK	Successful request
201	Created	Resource created (e.g., lead, task, subscription)
401	Unauthorized	Key missing, invalid or expired
403	Forbidden	Inactive account or key without permission for the operation
422	Unprocessable Entity	Validation or business rule (invalid fields, blocked stage, plan limit, WhatsApp window)
429	Too Many Requests	Per-minute request limit exceeded
502	Bad Gateway	External provider failure (e.g., WhatsApp sending)

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

The possible messages are: API Key não fornecida., API Key inválida. and API Key expirada.

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

When the account is suspended: { "message": "Conta inativa." }.

Validation error (fields):

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

Business rule. Examples:

• Blocked stage (there are mandatory pending tasks in the current stage):

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

• Plan limit reached:

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

• WhatsApp 24h window closed (Official / Cloud API only):

{
  "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
}

Returned when the WhatsApp provider refuses the send:

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

• 60 requests per minute, per API Key.
• When exceeded, the API responds 429 with the Retry-After header (in seconds) and the retry_after field in the body.
• The limit is per key (independent of IP).

Listings (GET /leads, GET /tasks) accept:

• page — page (default 1).
• per_page — items per page (default 50, maximum 200).

And return a meta object:

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

Sync tip: use the updated_since filter on GET /leads to fetch only the leads changed since the last query.

• Responses include success: true|false.
• Dates in ISO 8601.
• The ?include= parameter (in Leads) loads extra relations on demand; unknown tokens are ignored (they do not raise an error).