Erros

Todo erro da API usa a mesma forma JSON, compatível com o protocolo do Resend:

{"statusCode": 422, "name": "validation_error", "message": "…"}

name é um código de máquina estável (a chave que os SDKs usam); message é legível por humanos e pode mudar. Decida por statusCode e name, nunca por message.

Códigos de erro

Todos os códigos que esta implantação emite, por status. As mesmas condições chegam ao servidor MCP como resultados de ferramenta com este corpo, e ao relé SMTP como status do próprio protocolo — os nomes são os da API.

Pausas e bloqueios de envio

Três recusas significam "agora não, e não por causa da sua requisição". As três são 403 e determinísticas — nenhum laço de retentativa as resolve:

• sending_paused — a taxa de bounce duro ou de reclamação do próprio time na janela recente está no limite ou acima do guardrail, então o envio é recusado antes de chegar à fila. A mensagem informa a métrica, a taxa, a janela e o limite. Limpe a lista e diminua o ritmo até a taxa voltar para baixo da linha; insights de entregabilidade é o relatório que mostra quais endereços causaram isso.
• broadcasts_paused — só no envio de broadcast (POST /broadcasts/{id}/send). Ou o operador da instância pausou broadcasts para este time, ou a taxa agregada de bounce/reclamação da plataforma na região SES do remetente está se recuperando e a região inteira espera. E-mail transacional não é afetado, e a pausa se resolve sozinha.
• team_suspended — o operador da instância suspendeu o time. Nada é enviado até a reinstalação; só o operador pode liberar.

Duas proteções rodam antes de o e-mail chegar ao SES, no MepMail Cloud:

• Remetente disfarçado é recusado com 422 validation_error: nome do remetente ou assunto que mistura letras parecidas de alfabetos diferentes na mesma palavra (um а cirílico dentro de uma palavra latina), escreve uma palavra inteira com letras parecidas ao lado de palavras latinas, ou esconde caracteres invisíveis ou de inversão de direção. Escreva num alfabeto só e envie de novo.
• A revisão guarda o e-mail em vez de enviá-lo. Um time nos primeiros 30 dias cujo nome do remetente ou assunto imita banco, operadora, fisco ou aviso de segurança da conta, ou cujo pagamento foi bloqueado pelo antifraude da Stripe, fica retido para uma revisão rápida. A API continua respondendo 200 com o id do e-mail; o e-mail espera como queued e sai quando a revisão termina, e o painel mostra a retenção. Nada se perde.

Repetir requisições

• 4xx: repita apenas 409 concurrent_idempotent_requests (com a mesma chave de idempotência) e 429 (com backoff). O resto da faixa 4xx é determinístico — corrija a requisição ou a credencial. 403 sending_paused, 403 broadcasts_paused e 403 team_suspended também são determinísticos: esperar e repetir em laço não resolve.
• 5xx: repita com backoff exponencial e jitter. Envios com chave de idempotência são seguros de repetir; sem ela, um reenvio pode entregar duas vezes.

Idempotência

Os endpoints de envio aceitam um cabeçalho Idempotency-Key. Duas requisições com a mesma chave rodam uma vez; enquanto a primeira executa, a segunda responde 409 concurrent_idempotent_requests. Reuse a mesma chave ao repetir depois de um timeout — é isso que torna o reenvio seguro. Reusar uma chave com payload diferente é 409 invalid_idempotent_request: dê uma chave própria ao novo payload em vez de repetir.

Envios em lote

POST /emails/batch aceita até 100 e-mails. Com o cabeçalho x-batch-validation: permissive, itens inválidos voltam em errors por índice enquanto o subconjunto válido é aceito; por padrão (strict), um item inválido rejeita o lote inteiro. Um array acima do teto responde 422. Uma recusa que não é de um item — cota, uma pausa, o teto de contatos do plano — responde uma vez para a chamada inteira, nos dois modos de validação.

MCP

O servidor MCP expõe as mesmas condições: 429 rate_limit_exceeded no endpoint quando o orçamento de chamadas da conta acaba, e falhas de ferramenta como resultados com isError — leia o conteúdo de texto para o código e a mensagem.