Errors

The error envelope

When a request fails, Sendara returns an HTTP status in the 4xx or 5xx range and a JSON body with a single error object. The code field is a stable string that your program reads. The message field is for a person, and its wording can change. The status field repeats the HTTP status.

{
  "error": {
    "code": "from_not_verified",
    "message": "from_email domain is not a verified sending domain for this account",
    "status": 422
  }
}

A POST /v1/send/batch response uses the same shape in each entry. A failed item is { "success": false, "error": { … } }. A partial success is normal, and the API reports it item by item.

Error codes

The table gives the codes you meet most often. For each code it gives the HTTP status, the condition that raises it, and the recovery. Branch on code and not on the message text, because Sendara can add a code. Treat an unknown code as its HTTP status class.

One code carries two statuses. invalid_request returns 400 for a malformed body. It returns 422 on a suppression import that carries more than 10,000 entries.

Status families

• 400 / 422. The request is malformed, or it fails a business rule. Correct the input. An unchanged retry fails again.
• 401 / 403. The key is invalid, or its scope is too narrow. Check the key, the scope and the signature.
• 402. The send crossed a spend cap. Raise the cap, or wait for the next period.
• 404. The resource is absent, including cross-account access.
• 409. A conflict with existing state (suppression, idempotency, or a duplicate).
• 413. The payload is too large.
• 429. The limiter rejected the request. Read Retry-After, and wait for that many seconds.
• 5xx. The server hit a transient condition. Retry with the same idempotency key.

Handle an error

Each SDK raises a typed error. The error carries code, status and message. A 429 may also carry retryAfter when the response includes aRetry-After header. Branch on the code, then recover as the table above describes.

import { RateLimitError, Sendara, SendaraError } from "sendara";

const sendara = new Sendara(process.env.SENDARA_API_KEY!);

async function sendReceipt() {
  try {
    await sendara.emails.send({
      from: "[email protected]",
      to: "[email protected]",
      subject: "Your receipt",
      html: "<h1>Thanks for your order</h1>",
    });
  } catch (err) {
    if (err instanceof RateLimitError) {
      await new Promise((resolve) =>
        setTimeout(resolve, (err.retryAfter ?? 1) * 1000),
      );
    } else if (err instanceof SendaraError) {
      switch (err.code) {
        case "recipient_suppressed":
          return;
        case "from_not_verified":
          throw new Error("Verify your sending domain first");
        default:
          throw err;
      }
    } else {
      throw err;
    }
  }
}

await sendReceipt();

Retries & idempotency

Retry 429 and 5xx responses with exponential backoff. Because every send carries an idempotency_key, a replay after a timeout or internal_error returns the original result instead of sending twice. Reusing a key with a different body is rejected with idempotency_key_reused, so retries must send the exact same payload.

Rate-limit headers

Authenticated API requests that reach the account limiter carry your remaining budget, so you can slow down before it rejects a request. Authentication failures, public routes, and requests handled before that limiter do not necessarily include these headers. A limiter rejection also returns Retry-After in seconds and the rate_limit_exceeded code.

• X-RateLimit-Limit: the ceiling for the window.
• X-RateLimit-Remaining: requests left in the window.
• X-RateLimit-Reset: Unix epoch seconds when the window resets.

Verify an inbound signature

Sendara signs every webhook delivery, so you can prove that it came from Sendara. Each request carries Sendara-Signature, Sendara-Timestamp, Sendara-Event-Id, and Sendara-Event-Type. The signature is HMAC-SHA256 of "{timestamp}.{raw body}", hex-encoded, keyed with the subscription's signing secret. Verify over the raw request body before any JSON parsing or re-serialization, and compare in constant time.

import {
  verifyWebhook,
  WebhookVerificationError,
} from "sendara";

export function verifySendara(
  rawBody: string,
  headers: Record<string, unknown>,
  signingSecret: string,
): boolean {
  try {
    verifyWebhook(rawBody, headers, signingSecret, {
      toleranceSeconds: 5 * 60,
    });
    return true;
  } catch (error) {
    if (error instanceof WebhookVerificationError) return false;
    throw error;
  }
}