Status da API

A API do MeChat usa HTTP status codes e um envelope JSON consistente para indicar sucesso e erro.

Envelope de Sucesso

Quando a requisição é processada com sucesso, o retorno tem success: true e data.

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

Quando existe uma mensagem útil (por exemplo, criação, atualização, envio), ela vem em message.

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

Envelope de Erro

Quando a requisição falha, o retorno tem success: false e um message legível. O array errors é opcional e aparece quando existe detalhe estruturado.

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

Erros Estruturados

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

Erros de validação incluem 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"
    }
  ]
}

Erros que não pertencem a um campo específico não incluem 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 a requisição é processada corretamente, mas o resultado do negócio é negativo (por exemplo, um número não existe no WhatsApp), a resposta é 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."
}