Erreurs

Chaque réponse d’erreur a la même forme JSON, identique à celle de Resend :

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

Basez votre logique sur name, qui est stable. message est destiné aux humains et peut changer. Dans le SDK Node, les erreurs reviennent sous la forme { data: null, error } avec les trois mêmes champs ; les échecs réseau utilisent name: "application_error" et 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);
}

Tableau des erreurs

Statut	name	Signification et solution
400	invalid_idempotency_key	L’en-tête Idempotency-Key ne fait pas de 1 à 256 caractères.
401	missing_api_key	Aucun en-tête Authorization: Bearer sp_live_....
401	restricted_api_key	La clé n’a pas le droit de faire cela : une clé sending_access utilisée sur un endpoint qui n’envoie pas, ou une clé restreinte à un domaine qui envoie depuis un autre domaine.
403	invalid_api_key	La clé est inconnue, révoquée, ou n’est pas une clé SpacePost (par exemple une clé Resend re_).
403	invalid_from_address	Le domaine from n’est pas un domaine vérifié de votre équipe.
403	sending_paused	Votre équipe est en pause, généralement après des taux de rebonds ou de plaintes élevés, ou (lorsque vous passez tenant_id ou envoyez depuis un domaine appartenant à un tenant) ce tenant est en pause. Voir Mise en pause automatique.
403	validation_error	Une requête valide mais non autorisée : utiliser test.spacepost.dev pour écrire à des destinataires autres que votre équipe ou des adresses de test, ou dépasser la limite de domaines de votre forfait.
403	invalid_access	Session du tableau de bord sans accès à l’équipe demandée, ou POST /tenants/{ref}/unpause sur un tenant mis en pause pour son taux de rebonds ou de plaintes par une équipe qui n’est pas trusted. Contactez le support.
404	not_found	La ressource n’existe pas (ou appartient à une autre équipe), ou l’endpoint n’existe pas.
405	method_not_allowed	La méthode HTTP n’est pas prise en charge sur ce chemin.
409	concurrent_idempotent_requests	La même clé d’idempotence est encore en cours de traitement. Réessayez sous peu.
409	invalid_idempotent_request	La clé d’idempotence a déjà été utilisée avec un autre corps de requête.
422	validation_error	Un champ est manquant ou invalide. Le message le nomme. Aussi : « Only scheduled emails can be canceled », « Domain already registered », JSON invalide, un tenant_id qui entre en conflit avec le tenant du domaine, un external_id de tenant en double, la suppression d’un tenant qui a encore des domaines.
422	invalid_parameter	Un paramètre de requête ou de chemin est invalide.
429	rate_limit_exceeded	Dépassement de votre limite de requêtes par seconde. Attendez retry-after secondes.
429	daily_quota_exceeded	La limite d’envoi quotidienne a été atteinte (sandbox des nouveaux comptes, plafond de votre niveau de confiance, ou daily_limit d’un tenant).
429	monthly_quota_exceeded	La limite mensuelle du forfait Free a été atteinte. Passez à un forfait supérieur ou attendez.
451	security_error	L’e-mail a été bloqué par le filtrage de contenu (pièce jointe exécutable, indicateurs de phishing ou de spam). Modifiez le contenu ; ne réessayez pas tel quel.
500	application_error	Erreur inattendue de l’API. Réessayez avec un backoff.
500	internal_server_error	« An unexpected error occurred, please try again later ». Réessayez avec un backoff ; contactez le support si cela persiste.

Nouvelles tentatives

Réessayer ?	Erreurs
Oui, après les retry-after secondes	rate_limit_exceeded
Oui, avec un backoff exponentiel et la même Idempotency-Key	Les 500, erreurs réseau, concurrent_idempotent_requests
Non, corrigez la requête	400, 401, 403, 404, 422
Non, attendez la réinitialisation de la limite ou passez à un forfait supérieur	daily_quota_exceeded, monthly_quota_exceeded
Non, contactez le support (ou reprenez un tenant que vous avez vous-même mis en pause)	sending_paused, security_error

Webhooks et échecs asynchrones

Les erreurs ci-dessus sont renvoyées lorsque vous faites une requête. Les problèmes qui surviennent après l’acceptation d’un e-mail (rebonds, rejets) arrivent sous forme d’événements de webhook et dans le last_event de l’e-mail.

En SMTP, les mêmes situations sont renvoyées sous forme de codes de réponse SMTP : erreurs de quota 452, limitation de débit 421, expéditeur invalide 553, autres rejets 550, pannes temporaires 451.