Manejo de errores y observabilidad

Todo lo que el SDK puede lanzar es un error tipado que puedes capturar, y cada llamada de red emite telemetría que puedes observar.

Errores

import { CosmosPayAPIError, CosmosPayRequestError } from '@cosmosapp/pay_sdk';

try {
  await client.paymentIntents.fetch('missing');
} catch (err) {
  if (err instanceof CosmosPayAPIError) {
    // server responded with an error status
    console.error(err.status, err.code, err.body); // e.g. 404
  } else if (err instanceof CosmosPayRequestError) {
    // no usable response: network / TLS / timeout / offline
    console.error('Network/timeout:', err.cause);
  } else {
    throw err;
  }
}

• CosmosPayAPIError: la API respondió con 4xx/5xx. Campos: status, code, body.
• CosmosPayRequestError: la solicitud nunca se completó. Campo: cause.
• El cliente web agrega: CosmosPayWebError, WalletNotFoundError, WalletError (el usuario rechazó / billetera bloqueada), StellarSdkRequiredError, IntentError. Las clases de error de la API también se reexportan desde /web, así que catch funciona entre puntos de entrada.
• Los fallos de firma de webhook lanzan WebhookSignatureError.

Reintentos

Los fallos transitorios (errores de red, 408, 429, 5xx) se reintentan automáticamente, con 2 reintentos por defecto, respetando Retry-After. Ajústalo mediante new Client({ retries, timeout }).

Observabilidad

El cliente reemite telemetría REST:

client.on('request',     ({ method, url, attempt }) => {});
client.on('response',    ({ method, url, status, attempt }) => {});
client.on('rateLimited', ({ method, url, attempt }) => {});
client.on('debug',       (message) => {});

Conéctalos a tu logger/APM para rastrear o medir cada solicitud.

Referencias

• REST: La capa HTTP
• Client: El punto de entrada principal del SDK, un único cliente atómico que expone cada recurso a través de su propio administrador (un diseño atómico de un solo cliente).
• WebhookSignatureError: Se lanza cuando la verificación de la firma de un webhook falla.
• CosmosPayWebError: Clase base de todos los errores lanzados por @cosmosapp/pay_sdk/web.
• WalletNotFoundError: No se pudo detectar ninguna billetera de Stellar compatible en el entorno actual.
• WalletError: Se encontró una billetera pero la operación falló (el usuario rechazó, billetera bloqueada, etc.).
• StellarSdkRequiredError: Construir una transacción pay (o enviarla a Horizon) requiere el SDK de Stellar, que es una dependencia de par opcional
• IntentError: La intención / solicitud SEP-7 no se pudo interpretar o le faltan datos.