Documentation

Everything you need to integrate the rateship SDK into your Node backend.

Error Handling

Every error the SDK throws is a RateShipError (or a subclass). Inspect .code to branch on the failure kind, .provider to see which adapter raised it (if applicable), and .cause for the underlying error.

Thrown vs returned

getRates() returns { rates, errors } , per-provider failures go into errors[] as plain data. Only SDK-misuse (validation, configuration) throws.
createLabel(rate) throws on any failure. Single-provider, no partial-success shape.
webhooks.verify(...) throws WebhookVerificationError on signature mismatch. Never returns null on auth failure.

Error classes

class RateShipError extends Error {
  readonly code: ErrorCode;
  readonly provider?: "easypost" | "shippo" | "shipengine";
  readonly cause?: unknown;
}

class WebhookVerificationError extends RateShipError {
  // code is always "WEBHOOK_VERIFICATION_FAILED"
}

Per-provider error shape (inside errors[])

interface ProviderError {
  provider: "easypost" | "shippo" | "shipengine";
  code: ErrorCode;
  message: string;
}

Error codes

Code	When it fires
AUTH_FAILED	Provider returned 401 or 403. API key invalid, expired, or revoked.
TIMEOUT	Request exceeded the configured timeout (default 15s).
PROVIDER_ERROR	Provider returned a 4xx/5xx that isn't auth, or a semantic failure (e.g. "insufficient postage").
NETWORK_ERROR	DNS failure, connection reset, TLS handshake failure, etc.
VALIDATION_ERROR	Input didn't match the expected shape. Thrown before any provider call.
CONFIGURATION_ERROR	SDK misuse, missing apiKey, duplicate adapters, unsupported provider operation (e.g. ShipEngine webhook verify at v2.0).
WEBHOOK_VERIFICATION_FAILED	HMAC signature mismatch, stale timestamp, or malformed signature header.
UNKNOWN	Catch-all for errors that don't fit the above.

Handling patterns

import { RateShip, RateShipError, WebhookVerificationError } from "rateship";

try {
  const label = await client.createLabel(rate);
} catch (err) {
  if (!(err instanceof RateShipError)) throw err;

  switch (err.code) {
    case "AUTH_FAILED":
      // Provider API key is bad. Don't retry; surface to ops.
      break;
    case "TIMEOUT":
    case "NETWORK_ERROR":
      // Transient. Retry once after a backoff.
      break;
    case "PROVIDER_ERROR":
      // Semantic failure. err.message has the provider's own explanation
      // ("insufficient postage", "rate expired", etc.).
      break;
    case "VALIDATION_ERROR":
    case "CONFIGURATION_ERROR":
      // Code bug on our side. Throw again so the app-level error handler sees it.
      throw err;
  }
}

Next: Types Reference.