Skip to main content

​
エラーレスポンス形式

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認証ヘッダーが不正または不足しています
FORBIDDEN403加盟店アカウントが無効化されています

​
バリデーションエラー

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

​
決済エラー

コードHTTPステータス説明
PAYMENT_FAILED400決済処理に失敗しました
INVALID_STATUS400この操作は現在のステータスでは実行できません
INVALID_STATE400トランザクションの状態が不正です

​
返金エラー

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

​
リソースエラー

コードHTTPステータス説明
NOT_FOUND404指定されたリソースが見つかりません
FLOW_NOT_FOUND404決済フローが見つかりません
NO_DEFAULT_FLOW404デフォルトの決済フローが設定されていません
FLOW_NOT_ACTIVE400決済フローが無効化されています
CONNECTOR_CONFIG_NOT_FOUND404コネクタ設定が見つかりません
CONNECTOR_CONFIG_DISABLED400コネクタが無効化されています

​
冪等性エラー

コード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://sandbox-orchestration.zafapay.com/v2/payments', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
      'Content-Type': 'application/json',
      'X-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();
}