Handle errors
Branch on PaymentError, HTTP status, and stable error codes
The SDK converts local validation failures, network failures, and both REST API error envelopes to PaymentError.
import { PaymentError } from "@tradom/payment";
try {
await gatewayClient.gateway.createOrder(orderParams);
} catch (error) {
if (!(error instanceof PaymentError)) {
throw error;
}
switch (error.code) {
case "invalid_request":
case "parameter_missing":
case "parameter_invalid":
return showValidationError(error.param);
case "timeout":
case "network_error":
return retryLater();
default:
return showFallbackPaymentMethod();
}
}| Property | Description |
|---|---|
code | Stable error code for control flow |
httpStatus | HTTP status from the API; 0 for local and network failures |
param | Invalid parameter returned by the PaymentIntent API |
cause | Original fetch or abort error, when available |
Common error codes
| Category | Codes |
|---|---|
| Gateway authentication | missing_api_key (401), invalid_api_key (403) |
| Gateway request | invalid_json (400), internal_error (500) |
| Gateway session | session_expired, refresh_limit_reached, no_pool_wallet (all 409) |
| Gateway simulation | not_simulate_mode (400), select_asset_first (409), invalid_amount (400) |
| Gateway wallet check | not_blocked, reset_limit_reached (both 409) |
| Gateway asset and compliance | unsupported_asset (400), slippage_exceeded, risk_blocked, pending_review (409) |
| Public endpoints | link_unusable (409), too_many_requests (429) |
| PaymentIntent authentication | authentication_required (401) |
| Input | parameter_missing, parameter_invalid, crypto_asset_unsupported, url_invalid (all 400) |
| Resource and state | resource_missing (404), payment_link_inactive (409), payment_intent_unexpected_state (409; 400 on simulate_deposit) |
| SDK local | invalid_request, network_error, timeout, not_found, bad_response, signature_verification_failed |
API message values may be in Japanese or English. Use code, not message, for control flow.
Gateway service-level validation may return a descriptive string as code rather than a fixed code (for example "order_id is required", "unsupported token: …", "USD/JPY rate unavailable — …"). Branch only on documented fixed codes and treat everything else as a fallback.
A PaymentIntent refund above the remaining balance, or on an intent without a settlement, fails with payment_intent_unexpected_state (409), not parameter_invalid; parameter_invalid is only returned for a non-numeric or non-positive amount. crypto_asset_unsupported is also returned when the JPY reference rate is unavailable, not only for an unsupported stablecoin/network.
Gateway kyc_declined is not an error. It is returned as a successful createOrder response.