Errors

Helpers exported by @morevoice/sdk from src/lib/errors.ts.

API

Exported from @morevoice/sdk (source: packages/sdk-ts/src/lib/errors.ts).

ApiErrorType

type

The error types the API documents (from the spec’s ErrorEnvelope). Open: newer servers may send others.

type ApiErrorType = ErrorEnvelope["error"]["type"];

MoreVoiceErrorInit

interface

interface MoreVoiceErrorInit {
  message: string;
  /** HTTP status; undefined when no response arrived. */
  status?: number;
  type?: string;
  code?: string;
  param?: string;
  requestId?: string;
  docUrl?: string;
  details?: Record<string, unknown>;
  headers?: Headers;
  /** The parsed error body, as received. */
  raw?: unknown;
  cause?: unknown;
}

MoreVoiceError

class

The base of every error the SDK throws on purpose.

class MoreVoiceError extends Error {
  /** Stable class identity (survives minification and duplicate package copies). */
  readonly kind: string;
  /** HTTP status, or undefined when no response arrived (ConnectionError, client-side errors). */
  readonly status: number | undefined;
  /** The API error type (`invalid_request_error`, …), or a client-side type (`connection_error`, …). */
  readonly type: string;
  /** Stable, machine-readable code, e.g. `parameter_missing`, `dnc_listed`. Switch on it, never on `message`. */
  readonly code: string;
  /** The request parameter the error relates to, e.g. `to`. */
  readonly param: string | undefined;
  /** `req_…`: from the error body, else the X-Request-Id header. Quote it to support. */
  readonly requestId: string | undefined;
  /** Documentation of this error code. */
  readonly docUrl: string | undefined;
  /** Structured context, e.g. `required_scope` or the compliance `verdict`. */
  readonly details: Record<string, unknown> | undefined;
  /** The response headers. */
  readonly headers: Headers | undefined;
  /** The error body as received. */
  readonly raw: unknown;
  constructor(init: MoreVoiceErrorInit);
  static override [Symbol.hasInstance](value: unknown): boolean;
  /** A plain object for logs (no headers, no stack). */
  toJSON(): Record<string, unknown>;
}

InvalidRequestError

class

400 (also 413, 415, 422): a parameter is missing, malformed or not accepted.

class InvalidRequestError extends MoreVoiceError {
  readonly kind: string;
}

AuthenticationError

class

401: no, a malformed, a revoked or an expired API key.

class AuthenticationError extends MoreVoiceError {
  readonly kind: string;
}

PermissionError

class

403 (402 for plan limits): the key lacks a scope, the plan lacks a feature, or the mode does not match.

class PermissionError extends MoreVoiceError {
  readonly kind: string;
}

NotFoundError

class

404: no such object in this organisation and mode, or no such endpoint.

class NotFoundError extends MoreVoiceError {
  readonly kind: string;
}

ConflictError

class

409: the request conflicts with the object’s current state.

class ConflictError extends MoreVoiceError {
  readonly kind: string;
}

IdempotencyError

class

Idempotency-Key reused with different parameters, malformed, or still in progress (retry shortly).

class IdempotencyError extends MoreVoiceError {
  readonly kind: string;
}

RateLimitError

class

429: too many requests, or no call capacity right now.

class RateLimitError extends MoreVoiceError {
  readonly kind: string;
  /** How long the server asked to wait (Retry-After, else the RateLimit reset), in milliseconds. */
  readonly retryAfterMs: number | undefined;
  /** The window's request quota, when the server said. */
  readonly limit: number | undefined;
  /** Requests left in the window, when the server said. */
  readonly remaining: number | undefined;
  constructor(init: MoreVoiceErrorInit);
}

ComplianceError

class

A compliance rule blocked the action: the org DNC list, the national registry, missing §30A consent, the calling window, Shabbat.

class ComplianceError extends MoreVoiceError {
  readonly kind: string;
  /** The compliance verdict, when the API sent one (`details.verdict`). */
  get verdict(): unknown;
}

ApiError

class

5xx: something went wrong on MoreVoice’s side. Safe to retry with the same Idempotency-Key.

class ApiError extends MoreVoiceError {
  readonly kind: string;
}

ConnectionError

class

No response: DNS, connection refused or reset, TLS, or a per-attempt timeout (code: "timeout"). Retries were exhausted.

class ConnectionError extends MoreVoiceError {
  readonly kind: string;
}

WaitTimeoutError

class

calls.waitUntilEnded / campaigns.importCsv gave up waiting. last is the last state seen (the call or the import).

class WaitTimeoutError extends MoreVoiceError {
  readonly kind: string;
  readonly last: unknown;
  constructor(init: MoreVoiceErrorInit & { last?: unknown });
}

ImportFailedError

class

campaigns.importCsv: the import job failed as a whole (an unreadable file, not rejected rows).

class ImportFailedError extends MoreVoiceError {
  readonly kind: string;
  /** The failed import object. */
  readonly import: unknown;
  constructor(init: MoreVoiceErrorInit & { import: unknown });
}

CsvValidationError

class

campaigns.importCsv({ validate: true }): rows failed the client-side check; nothing was uploaded.

class CsvValidationError extends MoreVoiceError {
  readonly kind: string;
  /** The full validation report (row numbers, values, reasons). */
  readonly report: unknown;
  constructor(init: MoreVoiceErrorInit & { report: unknown });
}

MoreVoiceErrorClass

type

type MoreVoiceErrorClass = new (init: MoreVoiceErrorInit) => MoreVoiceError;

ERROR_CLASSES

constant

One class per documented error type. Keyed by the spec’s ErrorEnvelope type, so a type added to the spec breaks the build here until it is mapped (the exhaustiveness check the API contract asks for).

const ERROR_CLASSES: { readonly [T in ApiErrorType]: MoreVoiceErrorClass };

errorClassForStatus()

function

The class for an HTTP status, for error types newer than this SDK and non-envelope bodies (a proxy’s 502 page).

function errorClassForStatus(status: number): MoreVoiceErrorClass;

rateLimitQuota()

function

The window quota from the RateLimit headers (draft 07 limit=/remaining=, draft 08 r= + RateLimit-Policy q=, or the RateLimit-* / X-RateLimit-* pairs).

function rateLimitQuota(headers: Headers): { limit?: number; remaining?: number };

errorFromResponse()

function

The typed error for an HTTP error response (body parsed JSON, or text when it was not JSON).

function errorFromResponse(status: number, body: unknown, headers?: HeadersLike | Headers): MoreVoiceError;

toMoreVoiceError()

function

What the generated client’s error interceptor turns every failure into (installed by the MoreVoice class): a MoreVoiceError subclass, or the caller’s AbortError unchanged.

function toMoreVoiceError(error: unknown, response: Response | undefined): unknown;

isRetryableError()

function

Whether a failed request is worth retrying as is (the same policy as the client’s retrying fetch).

function isRetryableError(error: unknown): boolean;

errors

constant

Every error class, as one namespace: import { errors } from "@morevoice/sdk"; err instanceof errors.RateLimitError.

const errors;