Fehler

Jede Fehlerantwort hat dieselbe JSON-Form, identisch mit der von Resend:

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

Verzweige anhand von name, der stabil ist. message ist für Menschen gedacht und kann sich ändern. Im Node SDK kommen Fehler als { data: null, error } mit denselben drei Feldern zurück; Netzwerkfehler verwenden name: "application_error" und 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);
}

Fehlertabelle

Status	name	Bedeutung und Lösung
400	invalid_idempotency_key	Der Header Idempotency-Key ist nicht 1 bis 256 Zeichen lang.
401	missing_api_key	Kein Header Authorization: Bearer sp_live_....
401	restricted_api_key	Der Schlüssel darf das nicht: ein sending_access-Schlüssel an einem Endpoint, der nicht zum Senden dient, oder ein auf eine Domain beschränkter Schlüssel, der von einer anderen Domain sendet.
403	invalid_api_key	Der Schlüssel ist unbekannt, widerrufen oder kein SpacePost-Schlüssel (zum Beispiel ein re_-Schlüssel von Resend).
403	invalid_from_address	Die from-Domain ist keine verifizierte Domain deines Teams.
403	sending_paused	Dein Team ist pausiert, meist nach hohen Bounce- oder Beschwerderaten, oder (wenn du tenant_id übergibst oder von einer Domain eines Tenants sendest) dieser Tenant ist pausiert. Siehe Automatisches Pausieren.
403	validation_error	Eine Anfrage, die gültig, aber nicht erlaubt ist: test.spacepost.dev wird verwendet, um andere Empfänger als dein Team oder Testadressen anzuschreiben, oder das Domain-Limit deines Plans wird überschritten.
403	invalid_access	Dashboard-Sitzung ohne Zugriff auf das angefragte Team, oder POST /tenants/{ref}/unpause für einen Tenant, der wegen seiner Bounce- oder Beschwerderate pausiert wurde, durch ein Team, das nicht trusted ist. Wende dich an den Support.
404	not_found	Die Ressource existiert nicht (oder gehört zu einem anderen Team), oder der Endpoint existiert nicht.
405	method_not_allowed	Die HTTP-Methode wird für diesen Pfad nicht unterstützt.
409	concurrent_idempotent_requests	Derselbe Idempotenz-Schlüssel wird noch verarbeitet. Versuche es gleich noch einmal.
409	invalid_idempotent_request	Der Idempotenz-Schlüssel wurde bereits mit einem anderen Request-Body verwendet.
422	validation_error	Ein Feld fehlt oder ist ungültig. Die Meldung nennt es. Außerdem: “Only scheduled emails can be canceled”, “Domain already registered”, ungültiges JSON, eine tenant_id, die mit dem Tenant der Domain kollidiert, eine doppelte external_id eines Tenants, das Löschen eines Tenants, der noch Domains hat.
422	invalid_parameter	Ein Query- oder Pfadparameter ist ungültig.
429	rate_limit_exceeded	Das Limit für Anfragen pro Sekunde wurde überschritten. Warte retry-after Sekunden.
429	daily_quota_exceeded	Das tägliche Sendelimit wurde erreicht (die Sandbox für neue Konten, dein Limit nach Vertrauensstufe oder das daily_limit eines Tenants).
429	monthly_quota_exceeded	Das Monatslimit des Free-Plans wurde erreicht. Wechsle den Plan oder warte.
451	security_error	Die E-Mail wurde von der Inhaltsfilterung blockiert (ausführbarer Anhang, Phishing- oder Spam-Indikatoren). Ändere den Inhalt; wiederhole sie nicht unverändert.
500	application_error	Unerwarteter Fehler der API. Wiederhole mit Backoff.
500	internal_server_error	“An unexpected error occurred, please try again later”. Wiederhole mit Backoff; wende dich an den Support, wenn der Fehler bestehen bleibt.

Wiederholen

Wiederholen?	Fehler
Ja, nach den retry-after Sekunden	rate_limit_exceeded
Ja, mit exponentiellem Backoff und demselben Idempotency-Key	500er, Netzwerkfehler, concurrent_idempotent_requests
Nein, korrigiere die Anfrage	400, 401, 403, 404, 422
Nein, warte, bis das Limit zurückgesetzt wird, oder wechsle den Plan	daily_quota_exceeded, monthly_quota_exceeded
Nein, frage den Support (oder hebe die Pause eines Tenants auf, den du selbst pausiert hast)	sending_paused, security_error

Webhooks und asynchrone Fehler

Die obigen Fehler werden zurückgegeben, wenn du eine Anfrage stellst. Probleme, die nach der Annahme einer E-Mail auftreten (Bounces, Ablehnungen), kommen als Webhook-Events und im last_event der E-Mail an.

Über SMTP werden dieselben Bedingungen als SMTP-Antwortcodes zurückgegeben: Kontingentfehler 452, Rate Limiting 421, ungültiger Absender 553, sonstige Ablehnungen 550, vorübergehende Störungen 451.