Tratamento de erros & observabilidade

Tudo o que o SDK pode lançar é um erro tipado que você pode capturar, e toda chamada de rede emite telemetria que você pode observar.

Erros

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: a API respondeu com 4xx/5xx. Campos: status, code, body.
• CosmosPayRequestError: a requisição nunca foi concluída. Campo: cause.
• O cliente web adiciona: CosmosPayWebError, WalletNotFoundError, WalletError (usuário recusou / bloqueado), StellarSdkRequiredError, IntentError. As classes de erro da API também são reexportadas de /web, então o catch funciona em todos os pontos de entrada.
• Falhas de assinatura de webhook lançam WebhookSignatureError.

Retries

Falhas transitórias (erros de rede, 408, 429, 5xx) são repetidas automaticamente, com padrão de 2 retries, respeitando Retry-After. Ajuste via new Client({ retries, timeout }).

Observabilidade

O cliente reemite telemetria REST:

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

Conecte-os ao seu logger/APM para rastrear ou medir cada requisição.

Referências

• REST: A camada HTTP
• Client: O ponto de entrada principal do SDK, um único cliente atômico que expõe cada recurso por meio do seu próprio gerenciador (um design atômico de cliente único).
• WebhookSignatureError: Lançado quando a assinatura de um webhook falha na verificação.
• CosmosPayWebError: Classe base para todos os erros lançados pelo @cosmosapp/pay_sdk/web.
• WalletNotFoundError: Nenhuma carteira Stellar compatível pôde ser detectada no ambiente atual.
• WalletError: Uma carteira foi encontrada, mas a operação falhou (usuário recusou, bloqueado, etc.).
• StellarSdkRequiredError: Montar uma transação pay (ou enviá-la ao Horizon) requer o Stellar SDK, que é uma peer dependency opcional
• IntentError: A intenção / requisição SEP-7 não pôde ser interpretada ou está com dados faltando.