کلاس‌های خطا

کلاس پایه تمام خطاهایی که SDK تولید می‌کند. برای گرفتن هر چیزی که UnoPay پرتاب می‌کند این را بگیرید.

export class PaymentError extends Error {
  public code: string;
  public cause?: unknown;
  constructor(message: string, code: string, cause?: unknown);
}

فیلدها

خطاها

• PaymentError — به‌طور مستقیم با کد ADAPTER_NOT_FOUND، وقتی کلید درگاه در آبجکت adapters پاس‌داده‌شده به سازنده وجود ندارد.

نمونه کد

try {
  await unopay.createPayment('zarinpal', request);
} catch (err) {
  if (err instanceof PaymentError) {
    console.error(err.code, err.message, err.cause);
  }
}

SDK ورودی را پیش از تماس با درگاه یا به‌جای آن رد کرده است.

export class PaymentValidationError extends PaymentError {
  constructor(message: string, cause?: unknown);
}

فیلدها

خطاها

• ZarinpalAdapter constructor — وقتی config.merchantId خالی یا falsy باشد.
• ZarinpalAdapter.verifyCallback — وقتی Authority هم در query و هم در body نباشد، یا وقتی amount غایب یا NaN باشد. هر دو بررسی پیش از فراخوانی شبکه انجام می‌شوند.

نمونه کد

try {
  new ZarinpalAdapter({ merchantId: '' });
} catch (err) {
  if (err instanceof PaymentValidationError) {
    // err.code === 'VALIDATION_ERROR'
  }
}

درخواست هرگز پاسخ HTTP تولید نکرد: خطای DNS، قطع اتصال، یا خاتمه پس از ۱۰ ثانیه.

export class GatewayNetworkError extends PaymentError {
  constructor(message: string, cause?: unknown);
}

فیلدها

خطاها

• src/http.ts — هر رد شدن fetch و هر AbortError که کنترلر زمان‌بندی تولید کند. GatewayProviderError عمداً بدون تغییر دوباره پرتاب می‌شود تا به‌اشتباه خطای شبکه برچسب نخورد.

نمونه کد

try {
  await unopay.createPayment('zarinpal', request);
} catch (err) {
  if (err instanceof GatewayNetworkError) {
    await retryWithBackoff(() => unopay.createPayment('zarinpal', request));
  }
}

برای آداپتورهایی که امضای درگاه را اعتبارسنجی می‌کنند رزرو شده است. صادر شده و آماده است، اما در کد نسخه ۱٫۰٫۰ هرگز پرتاب نمی‌شود.

export class InvalidSignatureError extends PaymentError {
  constructor(message: string, cause?: unknown);
}

فیلدها

نمونه کد

// In your own adapter:
if (!isValidSignature(raw, req.secret)) {
  throw new InvalidSignatureError('Callback signature mismatch');
}

درگاه پاسخ داد و پاسخ موفق نبود. این رایج‌ترین خطایی است که مدیریت می‌کنید.

export class GatewayProviderError extends PaymentError {
  constructor(message: string, cause?: unknown);
}

فیلدها

خطاها

• UnoPay.createPayment — هر خطای غیر PaymentError که آداپتور پرتاب کند را در خود می‌پیچد. نمونه‌هایی که خودشان PaymentError هستند بدون تغییر عبور می‌کنند.
• UnoPay.verifyCallback — همان قاعده پیچیدن که در createPayment وجود دارد.
• ZarinpalAdapter.createPayment — وقتی کد پاسخ request.json برابر ۱۰۰ نباشد. پیام متن درگاه را حمل می‌کند و cause کل پاسخ را.
• src/http.ts — در هر وضعیت HTTP غیر ۲xx، که cause برابر متن پاسخ تنظیم می‌شود.

نمونه کد

try {
  await unopay.createPayment('zarinpal', request);
} catch (err) {
  if (err instanceof GatewayProviderError) {
    console.error('Gateway rejected:', err.message, err.cause);
  }
}