@cosmosapp/pay_sdkServer
Error handling & observability
The error classes the SDK throws, its retry behaviour, and the telemetry events you can hook into.
Everything the SDK can throw is a typed error you can catch, and every network call emits telemetry you can observe.
Errors
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— the API replied with 4xx/5xx. Fields:status,code,body.CosmosPayRequestError— the request never completed. Field:cause.- Web client adds:
CosmosPayWebError,WalletNotFoundError,WalletError(user rejected / locked),StellarSdkRequiredError,IntentError. The API error classes are re-exported from/webtoo, socatchworks across entries. - Webhook signature failures throw
WebhookSignatureError.
Retries
Transient failures (network errors, 408, 429, 5xx) are retried
automatically — default 2 retries, honoring Retry-After. Tune via
new Client({ retries, timeout }).
Observability
The client re-emits REST telemetry:
client.on('request', ({ method, url, attempt }) => {});
client.on('response', ({ method, url, status, attempt }) => {});
client.on('rateLimited', ({ method, url, attempt }) => {});
client.on('debug', (message) => {});Wire these into your logger/APM to trace or meter every request.
References
- Client: The main entry point of the SDK — a single, atomic client that exposes every resource through its own manager — an atomic, single-client design.
- CosmosPayWebError: Base class for every error thrown by
@cosmosapp/pay_sdk/web. - IntentError: The intent / SEP-7 request could not be interpreted or is missing data.
- REST: The HTTP layer
- StellarSdkRequiredError: Building a
paytransaction (or submitting to Horizon) requires the Stellar SDK, which is an optional peer dependency - WalletError: A wallet was found but the operation failed (user rejected, locked, etc.).
- WalletNotFoundError: No compatible Stellar wallet could be detected in the current environment.
- WebhookSignatureError: Thrown when a webhook signature fails verification.