Repository Public
1// Typed errors. Every failed API call throws an SPMailError (or a subclass); nothing here ever holds the API key.23export interface SPMailErrorInit {4 status: number5 code: string6 message: string7 details?: unknown8 requestId?: string | null9 retryAfterSec?: number | null10}1112/** Base class: an answer of the API with a non-2xx status (`status`, `code`, `message`, `details`, `requestId`). */13export class SPMailError extends Error {14 /** HTTP status; 0 when no answer was received (network failure, timeout). */15 readonly status: number16 /** Stable machine code of the API (`from_not_allowed`, `not_found`, …; docs/API.md §15). */17 readonly code: string18 readonly details: unknown19 /** `X-Request-Id` of the answer: quote it when reporting a problem. */20 readonly requestId: string | null21 /** Seconds announced by `Retry-After`, when present. */22 readonly retryAfterSec: number | null23 constructor(init: SPMailErrorInit, options?: { cause?: unknown }) {24 super(init.message, options)25 this.name = new.target.name26 this.status = init.status27 this.code = init.code28 this.details = init.details29 this.requestId = init.requestId ?? null30 this.retryAfterSec = init.retryAfterSec ?? null31 }32}33/** 400 — validation (`invalid_request`, `header_not_allowed`, `missing_variables`, …). */34export class BadRequestError extends SPMailError {}35/** 401 — `unauthenticated`, `invalid_api_key`, `key_revoked`, `key_expired`. */36export class AuthenticationError extends SPMailError {}37/** 403 — `insufficient_scope`, `from_not_allowed`, `external_send_denied`, … */38export class PermissionDeniedError extends SPMailError {}39/** 404 — unknown, or not visible to this key (deliberately indistinguishable). */40export class NotFoundError extends SPMailError {}41/** 409 — `idempotency_conflict`, `resync_required`, `address_taken`, `not_cancellable`, … */42export class ConflictError extends SPMailError {}43/** 422 — reserved: the API currently answers validation failures with 400 (BadRequestError). */44export class UnprocessableEntityError extends SPMailError {}45/** 429 — `rate_limited` (see `retryAfterSec`) or `daily_send_limit_exceeded`. */46export class RateLimitError extends SPMailError {}47/** 5xx — `internal`, `mail_server_unavailable`, `mail_server_error`. */48export class ServerError extends SPMailError {}49/** No answer: DNS, TCP, TLS or an aborted request (`code: "connection_error"`). */50export class ConnectionError extends SPMailError {}51/** The request, or `waitForDelivery`, exceeded its time budget (`code: "timeout"`). */52export class TimeoutError extends SPMailError {}53/** A webhook signature that does not verify (`code: "invalid_signature"`), thrown by `constructEvent`. */54export class SignatureVerificationError extends SPMailError {55 constructor(message: string) {56 super({ status: 0, code: "invalid_signature", message })57 }58}5960export function errorFromResponse(init: SPMailErrorInit): SPMailError {61 switch (init.status) {62 case 400: return new BadRequestError(init)63 case 401: return new AuthenticationError(init)64 case 403: return new PermissionDeniedError(init)65 case 404: return new NotFoundError(init)66 case 409: return new ConflictError(init)67 case 422: return new UnprocessableEntityError(init)68 case 429: return new RateLimitError(init)69 default: return init.status >= 500 ? new ServerError(init) : new SPMailError(init)70 }71}72