Erros - Vistum CRM

Formato padrão

Todas as respostas de erro seguem o mesmo formato:

{
  "error": "Descrição do erro",
  "hint": "Como corrigir (quando disponível)"
}

Código	Significado
`400 Bad Request`	Corpo da requisição inválido ou campo obrigatório ausente
`401 Unauthorized`	API Key ausente, inválida ou expirada
`402 Payment Required`	Limite do plano atingido ou recurso não disponível no plano atual
`403 Forbidden`	API Key sem o escopo necessário
`422 Unprocessable Entity`	Requisição válida mas não pode ser executada (ex: workspace sem WhatsApp)
`429 Too Many Requests`	Rate limit excedido
`500 Internal Server Error`	Erro interno do servidor

{ "error": "phone is required" }

O campo phone é obrigatório em todas as requisições.

{ "error": "Invalid phone number — minimum 10 digits" }

O número de telefone deve ter pelo menos 10 dígitos. Aceita formato E.164 ou DDD+número brasileiro.

{
  "error": "API key expired",
  "expiredAt": "2025-04-01T00:00:00.000Z"
}

A chave atingiu a data de expiração configurada. Gere uma nova chave.

{ "error": "Lead limit reached for this workspace's plan" }

O workspace atingiu o limite de leads do plano atual. Veja a tabela de limites ou faça upgrade.

{ "error": "API access not available on your plan. Upgrade to Growth or PRO." }

O acesso à API requer plano Growth ou superior.

{ "error": "Subscription inactive" }

A assinatura do workspace está inativa (cancelada, suspensa ou trial expirado).

{ "error": "Workspace has no WhatsApp instance configured" }

Para criar leads via API, o workspace precisa ter pelo menos uma instância de WhatsApp conectada.

Os seguintes erros são seguros para retry:

Os seguintes erros não devem ser retentados sem corrigir o problema: