Errorを処理する
PaymentError、HTTP status、安定したerror codeでの分岐
SDKはローカルvalidation、通信失敗、REST APIの両方のerror envelopeを 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();
}
}| プロパティ | 説明 |
|---|---|
code | 分岐に使う安定したerror code |
httpStatus | API応答のHTTP status。ローカル／通信errorは0 |
param | PaymentIntent APIが返した問題のparameter |
cause | 元のfetch／abort error（存在する場合） |
主なerror code
| 分類 | code |
|---|---|
| Gateway認証 | missing_api_key（401）、invalid_api_key（403） |
| Gateway request | invalid_json（400）、internal_error（500） |
| Gateway状態 | session_expired、refresh_limit_reached、no_pool_wallet（いずれも409） |
| Gateway simulate | not_simulate_mode（400）、select_asset_first（409）、invalid_amount（400） |
| Gateway wallet確認 | not_blocked、reset_limit_reached（いずれも409） |
| Gateway asset／compliance | unsupported_asset（400）、slippage_exceeded、risk_blocked、pending_review（409） |
| 公開endpoint | link_unusable（409）、too_many_requests（429） |
| PaymentIntent認証 | authentication_required（401） |
| 入力 | parameter_missing、parameter_invalid、crypto_asset_unsupported、url_invalid（いずれも400） |
| リソース／状態 | resource_missing（404）、payment_link_inactive（409）、payment_intent_unexpected_state（409。simulate_deposit では400） |
| SDKローカル | invalid_request、network_error、timeout、not_found、bad_response、signature_verification_failed |
APIの message は日本語と英語が混在する場合があります。制御フローでは message を比較せず、code を使ってください。
Gatewayのservice-level validationは、固定codeではなく説明文字列を code として返す場合があります（例: "order_id is required"、"unsupported token: …"、"USD/JPY rate unavailable — …"）。既知の固定codeだけで分岐し、それ以外はfallbackとして扱ってください。
PaymentIntentの返金で残高超過、またはsettlementのないintentへの返金は parameter_invalid ではなく payment_intent_unexpected_state（409）になります。parameter_invalid は amount が数値でない・0以下の場合のみです。crypto_asset_unsupported は未対応のstablecoin／networkに加え、JPY参照rateが取得できない場合にも返ります。
Gatewayの kyc_declined はerrorではありません。createOrder の正常レスポンスとして返ります。