エラー

すべてのエラーレスポンスは、Resend と同一の同じ JSON 形式です。

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

name は安定しているので、これで分岐してください。message は人が読むためのもので、変更されることがあります。Node SDK では、エラーは同じ 3 つのフィールドを持つ { data: null, error } として返ります。ネットワーク障害の場合は name: "application_error"、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);
}

エラー一覧

ステータス	name	意味と対処
400	invalid_idempotency_key	Idempotency-Key ヘッダーが 1 〜 256 文字ではありません。
401	missing_api_key	Authorization: Bearer sp_live_... ヘッダーがありません。
401	restricted_api_key	このキーでは実行できません。sending_access キーを送信以外のエンドポイントで使った、またはドメインを限定したキーで別のドメインから送信しました。
403	invalid_api_key	キーが存在しない、無効化されている、または SpacePost のキーではありません(たとえば Resend の re_ キー)。
403	invalid_from_address	from のドメインが、お使いのチームの検証済みドメインではありません。
403	sending_paused	チームが一時停止されています。通常はバウンス率や苦情率が高い場合です。または(tenant_id を渡した場合や、テナント所有のドメインから送信した場合は)そのテナントが一時停止されています。自動一時停止をご覧ください。
403	validation_error	リクエストは有効ですが、許可されていません。test.spacepost.dev を使ってチームやテスト用アドレス以外の宛先にメールを送った、またはプランのドメイン数の上限を超えた場合です。
403	invalid_access	リクエストされたチームへのアクセス権がないダッシュボードのセッション。または、バウンス率や苦情率のために一時停止されたテナントに対して、trusted ではないチームが POST /tenants/{ref}/unpause を実行した場合です。サポートにご連絡ください。
404	not_found	リソースが存在しない(または別のチームに属している)、またはエンドポイントが存在しません。
405	method_not_allowed	この HTTP メソッドは、このパスでサポートされていません。
409	concurrent_idempotent_requests	同じ冪等キーが、まだ処理中です。少し待ってから再試行してください。
409	invalid_idempotent_request	この冪等キーは、すでに異なるリクエストボディで使われています。
422	validation_error	フィールドが不足しているか、不正です。メッセージにフィールド名が示されます。このほか、“Only scheduled emails can be canceled”、“Domain already registered”、不正な JSON、ドメインのテナントと矛盾する tenant_id、テナントの external_id の重複、ドメインが残っているテナントの削除なども含まれます。
422	invalid_parameter	クエリまたはパスのパラメーターが不正です。
429	rate_limit_exceeded	1 秒あたりのリクエスト数の上限を超えました。retry-after の秒数だけ待ってください。
429	daily_quota_exceeded	1 日の送信上限に達しました(新規アカウントのサンドボックス、信頼レベルごとの上限、またはテナントの daily_limit)。
429	monthly_quota_exceeded	Free プランの月間上限に達しました。アップグレードするか、翌月まで待ってください。
451	security_error	メールがコンテンツのフィルタリングでブロックされました(実行可能な添付ファイル、フィッシングやスパムの兆候)。コンテンツを変更してください。そのまま再試行しないでください。
500	application_error	API で予期しないエラーが発生しました。バックオフを入れて再試行してください。
500	internal_server_error	“An unexpected error occurred, please try again later”。バックオフを入れて再試行してください。解消しない場合はサポートにご連絡ください。

再試行について

再試行する?	エラー
する。retry-after の秒数だけ待ってから	rate_limit_exceeded
する。指数バックオフと、同じ Idempotency-Key で	500 系、ネットワークエラー、concurrent_idempotent_requests
しない。リクエストを修正する	400、401、403、404、422
しない。上限がリセットされるのを待つか、アップグレードする	daily_quota_exceeded、monthly_quota_exceeded
しない。サポートに問い合わせる(ご自身で一時停止したテナントなら、一時停止を解除する)	sending_paused、security_error

Webhook と非同期の失敗

上記のエラーは、リクエストを送信したときに返されます。メールが受理された後に発生する問題(バウンスや拒否)は、Webhook イベントとして、またメールの last_event に反映されます。

SMTP では、同じ状況が SMTP の応答コードとして返されます。クォータのエラーは 452、レート制限は 421、不正な送信者は 553、その他の拒否は 550、一時的な障害は 451 です。