Status da API

Usamos HTTP status codes e um envelope JSON consistente para indicar sucesso e erro.

Envelope de Sucesso

Quando processamos a requisição com sucesso, retornamos success: true e data.

{
  "success": true,
  "data": {}
}

Quando existe uma mensagem útil (por exemplo, criação, atualização, envio), incluímos no campo message.

{
  "success": true,
  "message": "Operação realizada com sucesso.",
  "data": {}
}

Envelope de Erro

Quando a requisição falha, retornamos success: false e um message legível. O array errors é opcional e incluímos quando há detalhe estruturado.

{
  "success": false,
  "message": "Descrição clara do erro"
}

Erros Estruturados

Usamos o array errors quando há múltiplos problemas ou quando o erro precisa ser tratado por código.

Nos erros de validação, incluímos field para indicar o campo inválido:

{
  "success": false,
  "message": "Erro de validação",
  "errors": [
    {
      "code": "FIELD_REQUIRED",
      "field": "email",
      "message": "O campo email é obrigatório"
    }
  ]
}

Nos erros que não são de um campo específico, não incluímos field:

{
  "success": false,
  "message": "Operação não permitida",
  "errors": [
    {
      "code": "CHAT_ALREADY_FINALIZED",
      "message": "Não é possível enviar mensagens em um chat finalizado."
    }
  ]
}

Resultado de Negócio

Quando processamos a requisição corretamente, mas o resultado do negócio é negativo (por exemplo, um número não existe no WhatsApp), retornamos sucesso com data descrevendo o resultado.

{
  "success": true,
  "data": {
    "valid": false,
    "reason": "NUMBER_NOT_ON_WHATSAPP"
  }
}

Isso mantém a API previsível e evita que o cliente trate fluxo esperado como exceção.

Status Codes

Status	Descrição	Exemplo
200	Sucesso	Listagem, atualização, envio de mensagem
201	Recurso criado	Criação de contato, usuário, tag
400	Requisição inválida	JSON malformado, parâmetro inválido
401	Não autenticado	Token ausente ou inválido
403	Sem permissão	Acesso negado ao recurso
404	Não encontrado	Contato, chat ou usuário não existe
409	Conflito	Canal desconectado, recurso em uso
422	Validação falhou	Campo obrigatório ausente, formato inválido
429	Rate limit excedido	Muitas requisições no período
500	Erro interno	Falha inesperada no servidor

Exemplos por Status Code

400 - Requisição Inválida

{
  "success": false,
  "message": "JSON inválido na requisição."
}

401 - Não Autenticado

{
  "success": false,
  "message": "Token de autenticação não fornecido."
}

403 - Sem Permissão

{
  "success": false,
  "message": "Você não tem permissão para acessar este recurso."
}

404 - Não Encontrado

{
  "success": false,
  "message": "Contato não encontrado."
}

409 - Conflito

{
  "success": false,
  "message": "Canal WhatsApp desconectado.",
  "errors": [
    {
      "code": "CHANNEL_DISCONNECTED",
      "message": "O canal está desconectado. Reconecte o canal para continuar."
    }
  ]
}

422 - Validação Falhou

{
  "success": false,
  "message": "Erro de validação",
  "errors": [
    {
      "code": "FIELD_REQUIRED",
      "field": "phone",
      "message": "O campo phone é obrigatório."
    }
  ]
}

429 - Rate Limit Excedido

{
  "success": false,
  "message": "Muitas requisições. Tente novamente em alguns segundos.",
  "retry_after": 45
}

Para detalhes de limites, veja: Limites de Requisições

500 - Erro Interno

{
  "success": false,
  "message": "Erro interno do servidor. Tente novamente mais tarde."
}