错误

所有错误响应都使用相同的 JSON 结构，与 Resend 一致：

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

请根据 name 进行分支处理，它是稳定的。message 是给人看的，可能会变化。在 Node SDK 中，错误以 { 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	字段缺失或无效，message 会指明具体字段。此外还包括：“Only scheduled emails can be canceled”、“Domain already registered”、无效的 JSON、与域名所属租户冲突的 tenant_id、重复的租户 external_id，以及删除仍有域名的租户。
422	invalid_parameter	查询参数或路径参数无效。
429	rate_limit_exceeded	超出了每秒请求数限制。请等待 retry-after 秒。
429	daily_quota_exceeded	已达到每日发送上限（新账户沙盒、你的信任等级上限，或租户的 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。