API Real-Time: erros, limites e retornos da API

A API Real-Time da SafetyMails foi projetada para operar de forma estável mesmo em cenários de alto volume. As dúvidas mais frequentes relacionadas à API não envolvem a validação do email em si, mas sim erros de retorno, limites de uso e comportamentos esperados da API em situações específicas.
Este documento centraliza essas informações e explica como interpretar corretamente cada retorno, evitando confusão entre erro técnico, limite de plano e funcionamento normal do sistema.

Antes de executar qualquer verificação de email, cada requisição recebida pela API Real-Time passa por uma etapa de validações técnicas e de conformidade. Nessa etapa, o sistema avalia se a requisição está apta a ser processada, considerando critérios como autenticação, origem da chamada, limites de uso e disponibilidade de créditos.

Somente após essa análise preliminar a requisição é encaminhada para a etapa de verificação do email. Caso alguma dessas validações iniciais falhe, a API retorna imediatamente um erro técnico, sem executar a verificação.

Esse fluxo garante estabilidade, proteção contra uso indevido e previsibilidade no comportamento da API, sem causar bloqueio de formulários nem interrupção das integrações.

As mensagens abaixo só são exibidas quando o campo Success retorna como false na resposta da API. Nesses casos, a consulta não foi realizada com sucesso e o campo Msg informa o motivo da falha.
Esses erros estão relacionados a problemas de autenticação, parâmetros incorretos, origem da API, falta de créditos ou limites excedidos.
Exemplo de retorno com erroAbaixo está um exemplo de resposta da API quando ocorre um erro técnico e o campo Success retorna como false:

{
"Success": false,
"Email": "testeemail@safetymails.com",
"Referer": "www.safetymails.com",
"Status": "PENDENTE",
"Advice": "Unknown",
"Msg": "Referer inválido"
}

Nesse cenário, a requisição foi interrompida na etapa de validação preliminar (origem inválida), e nenhuma verificação de email foi executada.

Quando Success = false, nenhuma validação é executada.

Sandbox

• Ambiente destinado exclusivamente a testes
• Não reflete os limites reais do plano contratado
• Pode retornar respostas simuladas
• Não deve ser utilizado em formulários ativos

Produção

• Ambiente real de uso
• Consome créditos
• Aplica limites por minuto, hora e diário
• Reflete exatamente o comportamento descrito neste documento

Erros observados em produção não devem ser comparados com testes realizados apenas no sandbox.

Cada plano possui limites específicos de:

• requisições por minuto
• requisições por hora
• requisições diárias

Esses limites variam conforme o plano contratado e fazem parte das regras de uso justo da API. Os valores oficiais estão descritos no Termo de Uso da plataforma: https://www.safetymails.com/terms-of-use/

Quando o uso da API ultrapassa o limite permitido pelo plano:

• os formulários não são bloqueados
• a API continua respondendo
• as requisições que excederam o limite ficam com status PENDENTE
• o comportamento fica visível no gráfico de consumo diário da API

Esse mecanismo existe para preservar a experiência do usuário final, evitar falhas no front-end e sinalizar uso fora de conformidade com o plano contratado.

Quando os dados da API não aparecem como esperado, normalmente está relacionado a:

• uso incorreto do ambiente (sandbox x produção)
• autenticação inválida
• erro de interpretação da resposta
• requisições impactadas por limite momentâneo ou por expiração da API devido à não confirmação do pagamento da assinatura mensal ou anual (o cancelamento ocorre após 3 dias da falta de confirmação do pagamento)

Antes de escalar, é importante validar o ambiente utilizado, a API Key e os logs da integração.

Este cenário não representa erro técnico da API.
Quando o uso da API excede os limites do plano:

• o consumo aparece no gráfico diário marcado em cor lilás
• as requisições associadas ficam com status PENDENTE
• não há bloqueio de formulários
• não há interrupção da API

Esse comportamento existe para sinalizar uso fora de conformidade sem impactar a operação.

Este documento deve ser o primeiro ponto de consulta.
Caso, após a leitura deste artigo, a dúvida persista, o suporte técnico está disponível para ajudar durante o horário comercial.

• o erro persistir após seguir este guia
• houver indícios de erro específico de implementação
• o comportamento não corresponder ao descrito neste documento

Na maioria dos casos, ajustes na lógica de integração, volume de requisições ou plano contratado resolvem o cenário.