Tratamento de Erros - API Disparador

A API Disparador utiliza códigos de status HTTP padrão para indicar o sucesso ou falha das requisições. Todos os erros são retornados com uma estrutura JSON consistente.

Visão Geral

A API Disparador implementa um sistema robusto de tratamento de erros que:

Retorna códigos HTTP apropriados para cada tipo de erro
Fornece mensagens descritivas em português
Mantém estrutura JSON consistente em todas as respostas
Inclui detalhes técnicos quando necessário para debugging

Códigos de Status HTTP

200 OK

Requisição processada com sucesso

201 Created

Recurso criado com sucesso

400 Bad Request

Dados inválidos ou incompletos

401 Unauthorized

Token inválido ou ausente

404 Not Found

Recurso não encontrado

500 Internal Server Error

Erro interno do servidor

Estrutura da Resposta de Erro

Todas as respostas de erro seguem uma estrutura consistente:

{
  "timestamp": "2024-01-15T10:30:00",
  "status": 400,
  "error": "Erro de validação",
  "message": "{campaignId=Campanha não encontrada, evolutionUrl=URL da Evolution API é obrigatória}"
}

Campos da Resposta de Erro

timestamp

string

Data e hora do erro no formato ISO 8601

status

number

Código de status HTTP do erro

error

string

Título descritivo do tipo de erro

message

string

Descrição detalhada do erro ou objeto com erros de validação

Tipos de Erro Comuns

Erros de Validação (400)

Ocorrem quando os dados enviados não atendem aos requisitos:

curl -X POST https://{url-key}/api/campaigns \
  -H "Content-Type: application/json" \
  -H "X-Access-Token: {access_token}" \
  -d '{
    "name": "",
    "message": "Teste"
  }'

{
  "timestamp": "2024-01-15T10:30:00",
  "status": 400,
  "error": "Erro de validação",
  "message": "{name=Nome da campanha é obrigatório, evolutionUrl=URL da Evolution API é obrigatória, evolutionApiKey=Chave da Evolution API é obrigatória, evolutionInstance=Instância da Evolution é obrigatória}"
}

Erros de Autenticação (401)

Quando o access token é inválido ou não fornecido:

curl -X GET https://{url-key}/api/campaigns \
  -H "X-Access-Token: token-invalido"

{
  "timestamp": "2024-01-15T10:30:00",
  "status": 401,
  "error": "Credenciais inválidas",
  "message": "Access token inválido"
}

Erros de Recurso Não Encontrado (404)

Quando o recurso solicitado não existe:

curl -X GET https://{url-key}/api/campaigns/999999 \
  -H "X-Access-Token: {access_token}"

{
  "timestamp": "2024-01-15T10:30:00",
  "status": 404,
  "error": "Usuário não encontrado",
  "message": "Campanha com ID 999999 não foi encontrada"
}

Validações Específicas

Campanhas

Nome da Campanha

Obrigatório, 2-100 caracteres

Mensagem

Obrigatória, máximo 1000 caracteres

Contatos

Lista obrigatória, mínimo 1 contato

Evolution API

URL, chave e instância obrigatórias

Agendamento

Data Futura

Mínimo 5 minutos de antecedência

Formato ISO

Formato: YYYY-MM-DDTHH:mm:ss

Contatos

Número de Telefone

Formato: 5511999999999 (com código do país)

Nome

Opcional, máximo 100 caracteres

Tratamento de Erros no Cliente

JavaScript

try {
  const response = await fetch('https://{url-key}/api/campaigns', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Access-Token': '{access_token}'
    },
    body: JSON.stringify(campaignData)
  });

  if (!response.ok) {
    const errorData = await response.json();
    console.error('Erro da API:', errorData);
    
    switch (response.status) {
      case 400:
        console.error('Dados inválidos:', errorData.message);
        break;
      case 401:
        console.error('Token inválido:', errorData.message);
        break;
      case 404:
        console.error('Recurso não encontrado:', errorData.message);
        break;
      default:
        console.error('Erro inesperado:', errorData.message);
    }
  } else {
    const result = await response.json();
    console.log('Sucesso:', result);
  }
} catch (error) {
  console.error('Erro de rede:', error);
}

Python

import requests

try:
    response = requests.post(
        'https://{url-key}/api/campaigns',
        json=campaign_data,
        headers={
            'Content-Type': 'application/json',
            'X-Access-Token': '{access_token}'
        }
    )
    
    if response.status_code != 200:
        error_data = response.json()
        print(f'Erro {response.status_code}: {error_data["message"]}')
        
        if response.status_code == 400:
            print('Dados inválidos fornecidos')
        elif response.status_code == 401:
            print('Token de acesso inválido')
        elif response.status_code == 404:
            print('Recurso não encontrado')
        else:
            print('Erro inesperado do servidor')
    else:
        result = response.json()
        print('Sucesso:', result)
        
except requests.exceptions.RequestException as e:
    print(f'Erro de rede: {e}')

PHP

<?php
try {
    $curl = curl_init();
    curl_setopt_array($curl, [
        CURLOPT_URL => 'https://{url-key}/api/campaigns',
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => [
            'Content-Type: application/json',
            'X-Access-Token: {access_token}'
        ],
        CURLOPT_POSTFIELDS => json_encode($campaign_data)
    ]);
    
    $response = curl_exec($curl);
    $http_code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
    curl_close($curl);
    
    $result = json_decode($response, true);
    
    if ($http_code !== 200) {
        echo "Erro {$http_code}: {$result['message']}\n";
        
        switch ($http_code) {
            case 400:
                echo "Dados inválidos fornecidos\n";
                break;
            case 401:
                echo "Token de acesso inválido\n";
                break;
            case 404:
                echo "Recurso não encontrado\n";
                break;
            default:
                echo "Erro inesperado do servidor\n";
        }
    } else {
        echo "Sucesso: " . print_r($result, true);
    }
    
} catch (Exception $e) {
    echo "Erro: " . $e->getMessage();
}
?>

Boas Práticas

Sempre Verifique Status

Verifique o código de status HTTP antes de processar a resposta

Trate Erros Específicos

Implemente tratamento específico para cada tipo de erro

Log de Erros

Registre erros para debugging e monitoramento

Retry Inteligente

Implemente retry apenas para erros temporários (5xx)

Monitoramento e Debugging

Logs de Erro

A API registra todos os erros com detalhes para facilitar o debugging:

Timestamp preciso do erro
Stack trace completo para erros internos
Contexto da requisição (IP, headers, body)
Métricas de erro para monitoramento

Métricas Disponíveis

Taxa de Erro

Porcentagem de requisições com erro

Tempo de Resposta

Latência média das requisições

Erros por Tipo

Distribuição dos tipos de erro

Próximos Passos

Autenticação

Configure a autenticação corretamente

API Reference

Consulte a documentação completa

Suporte

Entre em contato para ajuda

Getting started

Development

​Visão Geral

​Códigos de Status HTTP

200 OK

201 Created

400 Bad Request

401 Unauthorized

404 Not Found

500 Internal Server Error

​Estrutura da Resposta de Erro

​Campos da Resposta de Erro

​Tipos de Erro Comuns

​Erros de Validação (400)

​Erros de Autenticação (401)

​Erros de Recurso Não Encontrado (404)

​Validações Específicas

​Campanhas

Nome da Campanha

Mensagem

Contatos

Evolution API

​Agendamento

Data Futura

Formato ISO

​Contatos

Número de Telefone

Nome

​Tratamento de Erros no Cliente

​JavaScript

​Python

​PHP

​Boas Práticas

Sempre Verifique Status

Trate Erros Específicos

Log de Erros

Retry Inteligente

​Monitoramento e Debugging

​Logs de Erro

​Métricas Disponíveis

Taxa de Erro

Tempo de Resposta

Erros por Tipo

​Próximos Passos

Autenticação

API Reference

Suporte

Visão Geral

Códigos de Status HTTP

Estrutura da Resposta de Erro

Campos da Resposta de Erro

Tipos de Erro Comuns

Erros de Validação (400)

Erros de Autenticação (401)

Erros de Recurso Não Encontrado (404)

Validações Específicas

Campanhas

Agendamento

Contatos

Tratamento de Erros no Cliente

JavaScript

Python

PHP

Boas Práticas

Monitoramento e Debugging

Logs de Erro

Métricas Disponíveis

Próximos Passos