Erros

Toda resposta de erro tem o mesmo formato JSON, idêntico ao do Resend:

{
  "statusCode": 422,
  "name": "validation_error",
  "message": "`from`: Invalid email address"
}

Use name para ramificar a lógica, pois ele é estável. A message é para pessoas e pode mudar. No SDK para Node, os erros voltam como { data: null, error } com os mesmos três campos; falhas de rede usam name: "application_error" e statusCode: null.

errors.ts

import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost();

const { data, error } = await spacepost.emails.send({
  from: "Acme <hello@acme.com>",
  to: "user@example.com",
  subject: "Hello",
  html: "<p>Hello</p>",
});

if (error) {
  switch (error.name) {
    case "rate_limit_exceeded":
      // wait about a second, then retry with the same idempotency key
      break;
    case "daily_quota_exceeded":
    case "monthly_quota_exceeded":
      // alert someone: you hit a limit
      break;
    case "validation_error":
    case "invalid_from_address":
      // a bug in your request: do not retry
      throw new Error(`${error.name}: ${error.message}`);
    default:
      console.error(error.statusCode, error.name, error.message);
  }
} else {
  console.log(data.id);
}

Tabela de erros

Status	name	Significado e solução
400	invalid_idempotency_key	O cabeçalho Idempotency-Key não tem de 1 a 256 caracteres.
401	missing_api_key	Falta o cabeçalho Authorization: Bearer sp_live_....
401	restricted_api_key	A chave não pode fazer isso: uma chave sending_access usada em um endpoint que não é de envio, ou uma chave restrita a um domínio enviando de outro domínio.
403	invalid_api_key	A chave é desconhecida, foi revogada ou não é uma chave do SpacePost (por exemplo, uma chave re_ do Resend).
403	invalid_from_address	O domínio de from não é um domínio verificado da sua equipe.
403	sending_paused	Sua equipe está pausada, em geral após taxas altas de rejeição ou de reclamação, ou (quando você passa tenant_id ou envia de um domínio pertencente a um tenant) esse tenant está pausado. Veja Pausa automática.
403	validation_error	Uma requisição válida, mas não permitida: usar test.spacepost.dev para enviar a destinatários que não sejam da sua equipe nem endereços de teste, ou exceder o limite de domínios do seu plano.
403	invalid_access	Sessão do painel sem acesso à equipe solicitada, ou POST /tenants/{ref}/unpause em um tenant que foi pausado pela taxa de rejeição ou de reclamação por uma equipe que não é trusted. Entre em contato com o suporte.
404	not_found	O recurso não existe (ou pertence a outra equipe), ou o endpoint não existe.
405	method_not_allowed	O método HTTP não é aceito neste caminho.
409	concurrent_idempotent_requests	A mesma chave de idempotência ainda está sendo processada. Tente novamente em instantes.
409	invalid_idempotent_request	A chave de idempotência já foi usada com um corpo de requisição diferente.
422	validation_error	Um campo está ausente ou é inválido. A mensagem o indica. Também: “Only scheduled emails can be canceled”, “Domain already registered”, JSON inválido, um tenant_id em conflito com o tenant do domínio, um external_id de tenant duplicado, a exclusão de um tenant que ainda tem domínios.
422	invalid_parameter	Um parâmetro de consulta ou de caminho é inválido.
429	rate_limit_exceeded	Acima do seu limite de requisições por segundo. Aguarde os segundos indicados em retry-after.
429	daily_quota_exceeded	O limite diário de envio foi atingido (sandbox de conta nova, o teto do seu nível de confiança ou o daily_limit de um tenant).
429	monthly_quota_exceeded	O limite mensal do plano Free foi atingido. Faça upgrade ou aguarde.
451	security_error	O e-mail foi bloqueado pela filtragem de conteúdo (anexo executável, indicadores de phishing ou de spam). Altere o conteúdo; não tente de novo como está.
500	application_error	Erro inesperado da API. Tente de novo com backoff.
500	internal_server_error	“An unexpected error occurred, please try again later”. Tente de novo com backoff; entre em contato com o suporte se persistir.

Novas tentativas

Tentar de novo?	Erros
Sim, após os segundos de retry-after	rate_limit_exceeded
Sim, com backoff exponencial e o mesmo Idempotency-Key	Erros 500, erros de rede, concurrent_idempotent_requests
Não, corrija a requisição	400, 401, 403, 404, 422
Não, aguarde o limite ser redefinido ou faça upgrade	daily_quota_exceeded, monthly_quota_exceeded
Não, fale com o suporte (ou retome um tenant que você mesmo pausou)	sending_paused, security_error

Webhooks e falhas assíncronas

Os erros acima são retornados quando você faz uma requisição. Os problemas que acontecem depois que um e-mail é aceito (rejeições, recusas) chegam como eventos de webhook e no last_event do e-mail.

Por SMTP, as mesmas condições são retornadas como códigos de resposta SMTP: erros de cota 452, limitação de taxa 421, remetente inválido 553, outras recusas 550, falhas temporárias 451.