Erros e limites da API de e-mail: códigos de status, retentativas e monitoramento

Enviar um e-mail em uma demo é fácil. Enviar cem mil por mês em produção significa se preparar para os momentos em que algo dá errado: uma chave revogada, um cartão vencido, um mês que acaba antes do esperado, um servidor de e-mail em um dia ruim.

Este guia explica cada resposta que o endpoint de envio da Inbixio retorna, o que o seu código deve fazer em cada caso e como acompanhar a entrega depois que você estiver em produção.

Duas etapas: aceito, depois entregue

Uma chamada a POST /api/send-email/ acontece em duas etapas:

1. A requisição à API. A Inbixio verifica sua chave, as permissões dela, sua assinatura, seu uso no mês e o corpo da requisição. Se estiver tudo certo, ela retorna 200 e coloca a mensagem na fila.
2. A entrega. Um instante depois, a Inbixio se conecta ao seu servidor SMTP e entrega a mensagem a ele. Cada mensagem é registrada como enviada ou com falha, e esses resultados alimentam os números do seu painel.

Ou seja, um 200 significa “aceito para entrega”, e não “na caixa de entrada”. Problemas na etapa 1 voltam como erros HTTP que o seu código pode tratar. Problemas na etapa 2, como uma senha SMTP errada, aparecem na taxa de entregas com falha do painel. A Inbixio faz uma única tentativa de entrega por mensagem; ela não repete uma entrega que falhou.

Cada resposta e o que fazer

As mensagens de erro chegam em error na maioria das respostas e em detail nos erros de autenticação, então leia os dois:

const body = await res.json().catch(() => ({}));
const reason = body.error ?? body.detail ?? res.statusText;

Repita só o que pode dar certo depois

Repetir um 401 cem vezes não vai tornar a chave válida; só vai encher seus logs. Separe os erros em dois grupos:

• Repita: erros de rede, timeouts, respostas 5xx e o 429 de rate limit (aquele com mensagem em detail). Espere o tempo indicado pelo header Retry-After; se ele não vier, use backoff exponencial com jitter e desista depois de algumas tentativas.
• Não repita: 400, 401, 402, 403 e o 429 de limite mensal (aquele com limit e sent). Esses precisam de uma pessoa ou de uma requisição diferente. Registre-os em destaque nos logs e crie alertas para 401, 402 e o 429 de limite mensal, porque eles interrompem todos os seus e-mails.

// 5xx and the short-term rate limit can succeed later; the monthly limit (body has `limit`) can't.
const retryable = (status, body) => status >= 500 || (status === 429 && body.limit === undefined);

export async function sendWithRetry(payload, attempts = 4) {
  for (let i = 0; i < attempts; i++) {
    let res;
    try {
      res = await fetch('https://backend.inbixio.com/api/send-email/', {
        method: 'POST',
        headers: { 'X-API-Key': process.env.INBIXIO_API_KEY, 'Content-Type': 'application/json' },
        body: JSON.stringify(payload),
        signal: AbortSignal.timeout(15_000),
      });
    } catch (err) {
      if (i === attempts - 1) throw err; // network error or timeout: retry
    }
    if (res?.ok) return res.json();
    if (res) {
      const body = await res.json().catch(() => ({}));
      if (!retryable(res.status, body)) {
        throw new Error(`Inbixio ${res.status}: ${body.error ?? body.detail ?? res.statusText}`);
      }
    }
    const retryAfter = Number(res?.headers.get('Retry-After')) * 1000;
    const delay = retryAfter || Math.min(30_000, 1000 * 2 ** i) * (0.5 + Math.random()); // 0.5s–30s with jitter
    await new Promise((r) => setTimeout(r, delay));
  }
  throw new Error('Inbixio: gave up after retries');
}

Sobre duplicatas: se uma requisição dá timeout, ela ainda pode ter sido aceita. Repeti-la pode, então, enviar o mesmo e-mail duas vezes. Para recibos e notificações isso costuma ser aceitável; para qualquer caso em que uma duplicata confundiria os usuários, registre o que você enviou no seu próprio banco de dados e confira antes de repetir.

Limites mensais

Cada plano inclui um número de e-mails por mês: 25.000 no Starter e 150.000 no Growth. A Inbixio conta os e-mails enviados com sucesso no mês do calendário atual. Quando você atinge o limite, os envios retornam 429 com o seu limit e a contagem atual em sent, até o próximo mês começar ou você fazer upgrade.

Não espere pelo 429:

• A página API Keys (chaves de API) mostra um card Usage Limit (limite de uso) com os e-mails enviados no mês em relação ao limite do seu plano.
• Crie um lembrete para conferir quando chegar a cerca de 80% do limite e planeje o upgrade antes de um grande lançamento ou importação.
• Para estimar seu volume passo a passo, veja como escolher um plano de API de e-mail.

Falhas de entrega (etapa 2)

Quando a API aceitou uma mensagem, mas o seu servidor SMTP a recusou, ela conta como uma entrega com falha. O painel mostra a taxa de Failed Deliveries (entregas com falha) dos últimos 7 dias, e não uma lista de mensagens individuais, então acompanhe essa taxa e confira as configurações do seu servidor quando ela subir. As causas mais comuns:

• Falha de autenticação: a senha da caixa de e-mail mudou, ou o provedor agora exige uma senha de app.
• Problemas de conexão: o host ou a porta nas configurações do servidor estão errados.
• Limites do provedor: seu provedor de e-mail limitou o envio diário da caixa de e-mail.
• Destinatário recusado: seu servidor recusou o endereço durante o envio. Os bounces que chegam depois como e-mails vão para a caixa de e-mail remetente, e não para a Inbixio, então confira essa caixa também.

A correção quase sempre está em Email Servers (servidores de e-mail) ou no seu provedor de e-mail. O artigo configurações SMTP explicadas cobre os casos mais comuns.

O que monitorar em produção

O painel da Inbixio traz o essencial:

• Email Sent (e-mails enviados) e a taxa de Failed Deliveries dos últimos 7 dias, cada um com a variação em relação aos 7 dias anteriores.
• Avg Latency (latência média): quanto tempo o seu servidor SMTP leva para aceitar os e-mails. Um salto repentino costuma vir antes das falhas.
• Gráficos de volume da API e de e-mails ao longo do ano, para identificar tendências e picos sazonais.
• Logs (registros) de cada chamada à API: ID do evento, endpoint, método, código de status, tempo de resposta e data e hora.

Do seu lado, acompanhe o número de respostas diferentes de 200 por código de status e crie alertas para quando aparecerem 401, 402 ou o 429 de limite mensal. Eles significam que todos os e-mails pararam, e seus usuários vão perceber antes dos seus logs.

Checklist

• Trate 200 como “na fila”; confira os resultados de entrega no painel
• Leia tanto error quanto detail nas respostas de erro
• Repita apenas erros de rede, timeouts, 5xx, 503 e o 429 de rate limit, respeitando o Retry-After
• Crie alertas para 401, 402 e o 429 de limite mensal
• Fique de olho no card Usage Limit antes de lançamentos e importações
• Acompanhe a taxa de Failed Deliveries e corrija as configurações SMTP rapidamente