Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 36 ยท REST vs SOAP

SOAP Faults vs HTTP Error Handling

Learn how SOAP 1.1 and 1.2 faults compare with HTTP status codes and RFC 9457 Problem Details, and build a translator that converts a fault into a REST error and back in Node.js.

Every service fails sometimes: a customer does not exist, a field is missing, a database is down. What matters is how clearly the failure is reported, because the caller has to decide what to do next: fix the request, retry later, or give up.

SOAP and REST report errors in very different places. SOAP puts the error in the message body, in a standard Fault element. REST puts the broad category in the HTTP status code and the details in a body whose shape the API designer chooses. In this lesson you will compare both, see how SOAP 1.1 and 1.2 differ, and write a translator you can reuse in gateways.

The SOAP 1.1 fault

A SOAP 1.1 fault has up to four children. Note that they are unqualified (no namespace prefix):

XML
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <soap:Fault>
      <faultcode>soap:Client</faultcode>
      <faultstring>Unknown product P-999</faultstring>
      <faultactor>urn:shop:catalog</faultactor>
      <detail><err:NotFound xmlns:err="urn:shop:errors"><err:sku>P-999</err:sku></err:NotFound></detail>
    </soap:Fault>
  </soap:Body>
</soap:Envelope>
  • faultcode is one of VersionMismatch, MustUnderstand, Client or Server, optionally with a dotted subcode.
  • faultstring is a human-readable message.
  • faultactor says which node raised the fault (rarely used).
  • detail carries application-specific, structured information.

The HTTP status for a SOAP 1.1 fault is 500, even when the fault is the client's own mistake. This is one reason people find SOAP errors blunt: the transport layer says "server error" while the body says "your request was wrong".

The SOAP 1.2 fault

SOAP 1.2 renamed and nested things, and uses a namespace for every element:

XML
<env:Fault>
  <env:Code><env:Value>env:Sender</env:Value></env:Code>
  <env:Reason><env:Text xml:lang="en">Unknown product P-999</env:Text></env:Reason>
  <env:Detail>...</env:Detail>
</env:Fault>

Sender replaces Client, Receiver replaces Server, Reason holds one or more language-tagged texts, and a fault can carry nested subcodes. SOAP 1.2 also maps Sender faults to HTTP 400 and Receiver faults to 500, which is more honest than 1.1.

Idea SOAP 1.1 SOAP 1.2
Caller's mistake Client Sender
Service's mistake Server Receiver
Message faultstring Reason/Text
HTTP status 500 400 or 500

HTTP errors and Problem Details

A REST API leans on status codes: 400 bad request, 401 not authenticated, 403 forbidden, 404 not found, 409 conflict, 422 unprocessable, 429 too many requests, 500 server error, 503 unavailable. Clients, proxies and monitoring tools understand these without reading the body.

For the body, the standard answer is Problem Details for HTTP APIs (RFC 9457, application/problem+json): a JSON object with type, title, status, detail and instance, plus any extension members you want.

JSON
{
  "type": "https://example.com/problems/unknown-product",
  "title": "Unknown product",
  "status": 404,
  "detail": "No product with SKU P-999",
  "sku": "P-999"
}

Translating between the two

A gateway that fronts a SOAP service with a REST API must convert in both directions. The mapping is a judgment call, but a reasonable default is: Client/Sender becomes a 4xx, Server/Receiver becomes a 5xx, and the fault string becomes detail.

Node.js Fault to Problem Details

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Both faults become the same JSON shape even though the XML differs. In a real gateway you would also keep a table of detail element names mapped to specific status codes (for example a NotFound detail becomes 404), so that "missing product" is a proper 404 rather than a generic 400.

And the other direction

When a SOAP client needs to call a REST back end, you build a fault from the HTTP response. The following program does that and sends the result through a real loopback server so you can see the status and body together.

Node.js HTTP error to SOAP fault

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice escapeXml: error messages often contain user input, and writing them unescaped into XML breaks the document or opens the door to injection.

Never put stack traces, SQL text or file paths into faultstring or detail on a public service. Log them on the server and return an error identifier the caller can quote to your support team.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which HTTP status does a SOAP 1.1 fault normally use?

    SOAP 1.1 over HTTP uses 500 for all faults, even when the client caused the error. SOAP 1.2 distinguishes Sender (400) from Receiver (500).
  2. 2. What replaced faultcode value Client in SOAP 1.2?

    SOAP 1.2 uses Sender for the caller's mistake and Receiver for the service's mistake.
  3. 3. What media type does RFC 9457 define for REST error bodies?

    Problem Details uses application/problem+json (and application/problem+xml for XML).
  4. 4. Why escape text before putting it in a faultstring?

    Unescaped markup in a message can corrupt the document or be used for injection.

Summary

  • SOAP faults live in the body (faultcode, faultstring, detail in 1.1; Code, Reason, Detail in 1.2); REST uses status codes plus a body.
  • SOAP 1.1 uses HTTP 500 for every fault; SOAP 1.2 maps Sender to 400.
  • Problem Details (application/problem+json) is the standard REST error body.
  • Gateways translate: caller faults to 4xx, service faults to 5xx, message to detail.
  • Escape messages and never leak internals in errors.

Next: Building a SOAP Server in Node.js