Errori

Ogni risposta di errore ha la stessa forma JSON, identica a quella di Resend:

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

Ragiona su name, che è stabile. message è pensato per le persone e può cambiare. Nell’SDK Node gli errori tornano come { data: null, error } con gli stessi tre campi; gli errori di rete usano 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);
}

Tabella degli errori

Stato	name	Significato e soluzione
400	invalid_idempotency_key	L’header Idempotency-Key non è lungo da 1 a 256 caratteri.
401	missing_api_key	Manca l’header Authorization: Bearer sp_live_....
401	restricted_api_key	La chiave non può fare questo: una chiave sending_access usata su un endpoint che non invia, oppure una chiave limitata a un dominio che invia da un altro dominio.
403	invalid_api_key	La chiave è sconosciuta, revocata o non è una chiave SpacePost (ad esempio una chiave re_ di Resend).
403	invalid_from_address	Il dominio di from non è un dominio verificato del tuo team.
403	sending_paused	Il tuo team è in pausa, di solito dopo alti tassi di rimbalzi o di reclami, oppure (quando passi tenant_id o invii da un dominio di proprietà di un tenant) è in pausa quel tenant. Vedi Pausa automatica.
403	validation_error	Una richiesta valida ma non consentita: usare test.spacepost.dev per scrivere a destinatari diversi dal tuo team o dagli indirizzi di test, oppure superare il limite di domini del tuo piano.
403	invalid_access	Sessione della dashboard senza accesso al team richiesto, oppure POST /tenants/{ref}/unpause su un tenant messo in pausa per il suo tasso di rimbalzi o di reclami da un team che non è trusted. Contatta l’assistenza.
404	not_found	La risorsa non esiste (o appartiene a un altro team), oppure l’endpoint non esiste.
405	method_not_allowed	Il metodo HTTP non è supportato su questo percorso.
409	concurrent_idempotent_requests	La stessa chiave di idempotenza è ancora in elaborazione. Riprova a breve.
409	invalid_idempotent_request	La chiave di idempotenza è già stata usata con un corpo della richiesta diverso.
422	validation_error	Un campo manca o non è valido. Il messaggio lo indica. Inoltre: “Only scheduled emails can be canceled”, “Domain already registered”, JSON non valido, un tenant_id in conflitto con il tenant del dominio, un external_id di tenant duplicato, l’eliminazione di un tenant che ha ancora dei domini.
422	invalid_parameter	Un parametro di query o di percorso non è valido.
429	rate_limit_exceeded	Superato il tuo limite di richieste al secondo. Attendi i secondi indicati da retry-after.
429	daily_quota_exceeded	È stato raggiunto il limite giornaliero di invio (la sandbox dei nuovi account, il tetto del tuo livello di fiducia, o il daily_limit di un tenant).
429	monthly_quota_exceeded	È stato raggiunto il limite mensile del piano Free. Passa a un piano superiore o attendi.
451	security_error	L’email è stata bloccata dal filtraggio dei contenuti (allegato eseguibile, indicatori di phishing o spam). Cambia il contenuto; non ritentare così com’è.
500	application_error	Errore imprevisto dell’API. Riprova con backoff.
500	internal_server_error	“An unexpected error occurred, please try again later”. Riprova con backoff; contatta l’assistenza se persiste.

Nuovi tentativi

Ritentare?	Errori
Sì, dopo i secondi indicati da retry-after	rate_limit_exceeded
Sì, con backoff esponenziale e la stessa Idempotency-Key	I 500, gli errori di rete, concurrent_idempotent_requests
No, correggi la richiesta	400, 401, 403, 404, 422
No, attendi il reset del limite o passa a un piano superiore	daily_quota_exceeded, monthly_quota_exceeded
No, rivolgiti all’assistenza (o riattiva un tenant che hai messo in pausa tu)	sending_paused, security_error

Webhook e fallimenti asincroni

Gli errori qui sopra vengono restituiti quando fai una richiesta. I problemi che avvengono dopo che un’email è stata accettata (rimbalzi, rifiuti) arrivano come eventi webhook e nel last_event dell’email.

Via SMTP, le stesse condizioni vengono restituite come codici di risposta SMTP: errori di quota 452, limitazione della frequenza 421, mittente non valido 553, altri rifiuti 550, guasti temporanei 451.