メインコンテンツへスキップ

​
エラーレスポンス形式

APIエラーは以下の形式で返されます。 
{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_error",
    "message": "エラーの説明",
    "request_id": "req_abc123xyz789"
  }
}
​
type
string
エラーの種類（authentication_error, invalid_request_error, payment_error, api_error）
​
code
string
エラーコード（下記参照）
​
message
string
エラーの説明文
​
request_id
string
リクエストID（サポートへの問い合わせ時に使用）
​
param
string
エラーの原因となったパラメータ名（バリデーションエラー時）
​
details
array
詳細なエラー情報（バリデーションエラー時）

​
認証エラー

コードHTTPステータス説明
unauthorized401認証ヘッダーが不正または不足しています
merchant_not_active403加盟店アカウントが無効化されています

​
バリデーションエラー

コードHTTPステータス説明
validation_error400リクエストパラメータが不正です。detailsフィールドに詳細が含まれます
invalid_amount400金額が不正です
amount_below_minimum400金額が最小値を下回っています
amount_above_maximum400金額が最大値を超えています
unsupported_currency400サポートされていない通貨です

​
決済エラー

コードHTTPステータス説明
payment_failed400決済処理に失敗しました
invalid_status400この操作は現在のステータスでは実行できません
invalid_state400トランザクションの状態が不正です
invalid_transaction400トランザクションが不正です
not_supported400この操作はサポートされていません
capture_failed400キャプチャに失敗しました
refund_failed400返金に失敗しました
card_limit_exceeded400月間カード決済上限を超過しました
email_limit_exceeded400月間メール決済上限を超過しました
recurring_not_supported400コネクタが継続決済をサポートしていません

​
Webhook決済エラーコード

決済が失敗した場合、payment.failed Webhookには、すべての決済プロバイダーで統一された形式の詳細なエラー情報が含まれます。

​
エラー構造

{
  "event": "payment.failed",
  "error": {
    "code": "card_declined",
    "category": "soft_decline",
    "message": "カードが拒否されました",
    "recommended_action": "use_different_card",
    "psp_error": {
      "code": "card_declined",
      "decline_code": "generic_decline"
    }
  }
}

​
エラーカテゴリ

カテゴリ説明推奨アクション
authentication3DS認証が必要顧客を認証ページにリダイレクト
soft_decline一時的な失敗リトライまたは別のカードを使用
hard_decline永続的な失敗同じカードでリトライしない
gateway_error決済ゲートウェイの問題後でリトライ

​
統一エラーコード

コードカテゴリ説明推奨アクション
authentication_requiredauthentication3DS認証が必要contact_customer
authentication_failedsoft_decline3DS認証に失敗retry
card_declinedsoft_declineカードが拒否されましたuse_different_card
insufficient_fundssoft_decline残高不足use_different_card
expired_cardhard_declineカードの有効期限切れuse_different_card
invalid_cardhard_declineカード番号が無効use_different_card
invalid_cvcsoft_declineセキュリティコードが無効retry
invalid_expirysoft_decline有効期限が無効retry
fraud_detectedhard_decline不正利用の疑いnone
stolen_cardhard_decline盗難カードnone
lost_cardhard_decline紛失カードnone
processing_errorgateway_error処理エラーretry
gateway_timeoutgateway_errorゲートウェイタイムアウトretry
gateway_unavailablegateway_errorゲートウェイ利用不可retry
unknown_errorsoft_decline不明なエラーuse_different_card

​
ハンドリング例

// Webhookハンドラー
app.post('/webhooks/zafapay', (req, res) => {
  const { event, error } = req.body;

  if (event === 'payment.failed' && error) {
    switch (error.category) {
      case 'authentication':
        // 顧客に認証リンク付きメールを送信
        notifyCustomerForAuth(error.message);
        break;
      case 'soft_decline':
        // リトライまたは別のカードを要求
        if (error.recommended_action === 'retry') {
          scheduleRetry();
        } else {
          requestNewCard();
        }
        break;
      case 'hard_decline':
        // リトライしない、顧客に通知
        notifyCustomerCardInvalid(error.message);
        break;
      case 'gateway_error':
        // 一時的な問題、リトライをスケジュール
        scheduleRetryWithBackoff();
        break;
    }
  }

  res.json({ received: true });
});
psp_errorフィールドには、デバッグ用に元の決済プロバイダーのエラー詳細が含まれます。

​
返金エラー

コードHTTPステータス説明
invalid_amount400返金額が決済額を超えています
invalid_status400返金可能なステータスではありません（completedのみ返金可能）

​
リソースエラー

コードHTTPステータス説明
not_found404指定されたリソースが見つかりません
flow_not_found404決済フローが見つかりません
no_default_flow404デフォルトの決済フローが設定されていません
flow_not_active400決済フローが無効化されています
connector_config_not_found404コネクタ設定が見つかりません

​
冪等性エラー

コードHTTPステータス説明
idempotency_key_mismatch400同じ冪等キーで異なるリクエストが送信されました
idempotency_key_in_use409冪等キーが現在処理中です

​
システムエラー

コードHTTPステータス説明
internal_error500内部エラーが発生しました。サポートにお問い合わせください

​
エラーハンドリングのベストプラクティス

1

HTTPステータスコードを確認

  • 4xx: クライアントエラー（リクエストの修正が必要）
  • 5xx: サーバーエラー（リトライ可能）
2

エラーコードで処理を分岐

error.codeを使用して、エラータイプに応じた処理を実装してください
3

リトライ戦略

5xxエラーやidempotency_key_in_useの場合は、指数バックオフでリトライしてください

​
サンプルコード

Node.js
async function createPayment(data) {
  const response = await fetch('https://api.sandbox.zafapay.com/v1/payments', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
      'Content-Type': 'application/json',
      'Idempotency-Key': generateIdempotencyKey()
    },
    body: JSON.stringify(data)
  });

  if (!response.ok) {
    const { error } = await response.json();

    // request_id をログに記録（サポートへの問い合わせ時に使用）
    console.error(`API Error [${error.request_id}]:`, error.code, error.message);

    switch (error.type) {
      case 'authentication_error':
        // トークンの再取得が必要
        throw new AuthError(error.message);

      case 'invalid_request_error':
        // リクエストパラメータを確認
        if (error.details) {
          console.error('Validation errors:', error.details);
        }
        throw new ValidationError(error.message);

      case 'payment_error':
        // 決済失敗（別の決済方法を試す等）
        throw new PaymentError(error.message);

      case 'api_error':
        // リトライ可能
        throw new RetryableError(error.message);

      default:
        throw new Error(error.message);
    }
  }

  return response.json();
}