Error codes

The PristineSend API uses conventional HTTP status codes to indicate success or failure. All error responses share the same JSON envelope.

Error format

Every non-2xx response body is a JSON object with a single error field:

{
  "error": "Human-readable description of the error"
}

For 500 errors triggered by Resend, the response may also include a details field with Resend's error message.

400 Bad Request

The request was malformed or missing required fields. Fix the request before retrying.

Status	Error message	Cause / Fix
400	`Missing required fields: to, subject, html`	One or more required body fields are absent. Fix: Include to, subject, and html in the JSON body.
400	`No Resend API key configured for this workspace`	Your PristineSend workspace has no Resend key set. Fix: Go to Settings → Sending and add your Resend API key.

401 Unauthorized

Authentication failed. The API key is missing, malformed, or invalid.

Status	Error message	Cause / Fix
401	`Missing or invalid Authorization header`	The Authorization header is absent or malformed. Fix: Include Authorization: Bearer ps_live_YOUR_KEY in every request.
401	`Invalid API key`	The key was not found or has been rotated. Fix: Regenerate your key in Settings → API Keys and update your env vars.

500 Server Error

An unexpected error occurred. These are safe to retry with exponential backoff.

Status	Error message	Cause / Fix
500	`Failed to send email`	Resend rejected the send — details in the details field. Fix: Check the details field and your Resend account for quota or domain issues.
500	`Internal server error`	An unexpected error occurred in PristineSend. Fix: Retry with exponential backoff. If the issue persists contact support.

Handling errors

Branch on the HTTP status code rather than the error string, as messages may change:

"color:#ff7b72">const res = "color:#ff7b72">await fetch("https://pristinesend.com/api/v1/send", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ps_live_YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ to, subject, html }),
})

if (!res.ok) {
  "color:#ff7b72">const { error } = "color:#ff7b72">await res.json()

  if (res.status === 401) {
    // API key is missing or invalid — check your key
    throw new AuthError(error)
  }

  if (res.status === 400) {
    // Caller mistake — fix the request body
    throw new ValidationError(error)
  }

  // 500 — transient error, safe to retry with backoff
  throw new ServerError(error)
}

"color:#ff7b72">const { id } = "color:#ff7b72">await res.json()