Errors
Typed error classes thrown by the Amboss Payments SDK: ApiError, ConfigError, NetworkError, WebhookVerificationError, DecryptionError, and PaymentSendError.
Every failure the SDK surfaces is a typed error class, so you can branch on instanceof and pull structured context off the error instead of parsing strings.
Error classes
| Class | Thrown when |
|---|---|
ApiError | The API returned an error. Carries status and graphqlErrors. |
ConfigError | The SDK is misconfigured, for example a resource call without a serviceApiKey. |
NetworkError | The request failed to reach the API (DNS, connection, timeout). |
WebhookVerificationError | A webhook signature failed to verify. Carries a typed code. See Webhooks. |
DecryptionError | The team password could not decrypt the node macaroon (wrong password). |
PaymentSendError | The node rejected or failed the payment during a send. |
ApiError, ConfigError, and NetworkError come from @ambosstech/core and are re-exported from @ambosstech/payments, so you can import them all from one place.
Handling API errors
Resource calls (environments, wallets, transactions) throw ApiError on an API-level failure:
import { ApiError, ConfigError, NetworkError } from "@ambosstech/payments";
try {
await payments.wallets.list({ environmentId });
} catch (err) {
if (err instanceof ApiError) {
console.error(err.status, err.message, err.graphqlErrors);
} else if (err instanceof ConfigError) {
console.error("SDK misconfigured:", err.message);
} else if (err instanceof NetworkError) {
console.error("Network failure:", err.message);
} else {
throw err;
}
}Handling send errors
transactions.send can fail locally (wrong password) or node-side (routing, liquidity):
import { DecryptionError, PaymentSendError } from "@ambosstech/payments";
try {
await payments.transactions.send(params);
} catch (err) {
if (err instanceof DecryptionError) {
// wrong team password, macaroon could not be decrypted
} else if (err instanceof PaymentSendError) {
// the node rejected or failed the payment
} else {
throw err;
}
}Webhook verification failures throw WebhookVerificationError with a typed code you can map to an HTTP response. See the error codes table.