SOAPless
無料で始める
ブログへ戻る
soap-errorstroubleshootingweb-services

SOAP Fault: Server Was Unable to Process Request の完全な解決ガイド

SOAPless Team8 min read

SOAP 連携の開発で最も厄介なエラーの一つが 「Server was unable to process request」 です。このエラーメッセージはサーバー側で何かが失敗したことだけを伝え、具体的な原因についてはほとんど情報を与えてくれません。この記事では、このエラーの原因を体系的に分析し、段階的な解決方法をコード例付きで解説します。

このエラーの正体

このエラーは SOAP Fault エンベロープとして返されます。典型的なレスポンスは以下のようになります。

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <soap:Fault>
      <faultcode>soap:Server</faultcode>
      <faultstring>Server was unable to process request.</faultstring>
      <detail />
    </soap:Fault>
  </soap:Body>
</soap:Envelope>

faultcode が soap:Server（SOAP 1.2 では soap:Receiver）の場合、問題はサーバー側で発生しています。ただし、実際にはクライアント側のリクエストに起因する問題であっても、サーバーが soap:Server を返してしまうケースが少なくありません。

原因 1: 必須パラメータの欠落

最も頻繁に遭遇する原因です。SOAP オペレーションは WSDL で厳密な型契約が定義されており、必須要素が欠けていたり nil 値を送信すると、サーバー側のデシリアライゼーションが例外をスローします。

WSDL のスキーマ定義を確認しましょう。

<xs:element name="GetUserRequest">
  <xs:complexType>
    <xs:sequence>
      <xs:element name="userId" type="xs:int" minOccurs="1"/>
      <xs:element name="includeProfile" type="xs:boolean" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>
</xs:element>

minOccurs="1" のフィールドは必須です。以下のように空で送信するとエラーが発生します。

<!-- NG: userId が空 -->
<GetUserRequest>
  <userId></userId>
</GetUserRequest>

<!-- OK: 有効な値を指定 -->
<GetUserRequest>
  <userId>42</userId>
</GetUserRequest>

対処法: WSDL の XSD 定義を精査し、すべての必須パラメータに有効な値が設定されているか確認してください。

原因 2: 型の不一致

SOAP サービスは強い型付けを持ちます。文字列を整数型のフィールドに送ったり、日付のフォーマットが合わない場合にデシリアライゼーションエラーが発生します。

<!-- NG: xs:dateTime に日付のみを送信 -->
<startDate>2026-03-21</startDate>

<!-- OK: ISO 8601 の完全なフォーマット -->
<startDate>2026-03-21T00:00:00</startDate>

xs:date と xs:dateTime は似ているようで互換性がありません。同様に xs:decimal と xs:integer、xs:boolean の true と 1 も区別が必要です。

対処法: WSDL のスキーマ型を正確に確認し、XSD バリデーターでリクエストを検証してから送信しましょう。

原因 3: XML 名前空間の問題

名前空間の不一致は、SOAP 連携が静かに壊れる原因として非常に多いパターンです。サーバーのデシリアライザーは要素が正しい名前空間 URI に属しているかを検証します。

<!-- NG: 名前空間の指定がない -->
<GetUserRequest>
  <userId>42</userId>
</GetUserRequest>

<!-- OK: targetNamespace を正しく宣言 -->
<tns:GetUserRequest xmlns:tns="http://example.com/services">
  <tns:userId>42</tns:userId>
</tns:GetUserRequest>

対処法: WSDL の targetNamespace を確認し、すべてのオペレーション要素に正しい名前空間を宣言してください。手動で XML を構築している場合は、node-soap や zeep（Python）などのライブラリの利用を検討しましょう。

原因 4: 認証・認可の失敗

多くの SOAP サービスは WS-Security ヘッダーや HTTP Basic Auth を要求します。認証情報が不足している場合でも、具体的な 401 ではなく汎用的な Server Fault を返すサーバーがあります。

<soap:Header>
  <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
    <wsse:UsernameToken>
      <wsse:Username>your_username</wsse:Username>
      <wsse:Password>your_password</wsse:Password>
    </wsse:UsernameToken>
  </wsse:Security>
</soap:Header>

対処法: API プロバイダーに必要な認証方式を確認し、既知の正しい認証情報で軽量なオペレーション（ping やバージョン取得）をテストしてください。

原因 5: サーバー側の一時的障害

リクエストの内容に問題がなくても、サーバーが依存するデータベースや外部サービスのタイムアウトによってこのエラーが発生することがあります。

見分け方: まったく同じリクエストを数分後に再送信してください。成功すれば一時的な障害です。

// Node.js でのリトライロジック例
async function callSoapWithRetry(request, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const result = await soapClient.call(request);
      return result;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

デバッグのステップバイステップ手順

このエラーに遭遇したら、以下の順序で調査してください。

  1. SOAP ログの有効化: 生の XML リクエストとレスポンスをキャプチャする。ライブラリの抽象化ではなく、実際の XML を見る。
  2. WSDL に対するリクエストの検証: SoapUI の「Validate」機能や XSD バリデーターを使う。
  3. 最小限のリクエストに簡略化: パラメータを最小限まで削り、動作するか確認する。動いたらパラメータを一つずつ追加する。
  4. サーバーログの確認: サービスプロバイダーにスタックトレースの提供を依頼する。
  5. 動作するサンプルとの差分確認: ドキュメントのサンプルリクエストと自分のリクエストを要素ごとに比較する。

SOAP デバッグの根本的な課題

SOAP のデバッグが困難な根本原因は、XML エンベロープの厳密な名前空間契約、WS-Security ヘッダー、そして不透明なエラーメッセージというフォーマット自体の複雑さにあります。すべての連携でスキーマの精査、正確な XML の構築、問題発生時の地道なデバッグが必要になります。

SOAP Fault との戦いにアプリケーション開発以上の時間を費やしているなら、XML の複雑さを自動処理するプロキシ層の導入を検討する価値があります。SOAPless は SOAP サービスを REST API に変換し、標準的な JSON を送るだけで正しい SOAP エンベロープを自動構築して JSON でレスポンスを返します。WSDL の URL を入力するだけで、約 30 秒で動作する REST エンドポイントが得られます。

いずれの方法でも、上記のデバッグ手順は生の SOAP レイヤーを診断する際に役立つはずです。

ブログへ戻る