## TL;DR

SOAP faults nest the real error inside envelope and body elements that string matching mangles. Parse with a real XML parser, navigate to the Fault element, and read faultcode and faultstring. Never regex XML; the nesting always wins.

## Error

```text
Agent failed: regex found no error in the SOAP fault response; the actual faultcode was nested two levels deep.
```

## Steps

1. Parse the response with an XML parser (ElementTree or equivalent), not string search. Expected: a navigable document.
2. Find the Fault element under Body (handle namespaces with wildcards). Expected: the fault node.
3. Read its faultcode and faultstring children as text. Expected: the real error, for example INVALID_FIELD.
4. Map the faultcode to your handling: validation, auth, or data errors each get their path. Expected: classified errors, not one big catch.
5. Log the full fault for audit. Expected: debuggability preserved.

## When to use

- SOAP API error parsing fails.
- An agent uses regex on XML responses.
- Fault details are nested or namespaced.

## When not to use

- REST JSON errors (parse JSON normally).
- Successful responses (nothing to parse).

## Tool compatibility

- Python xml.etree.ElementTree or lxml; any SOAP client.
- Salesforce SOAP API faults.

## Variant phrasings

### nested fault xml

Parse, do not regex.

### faultcode not found by string search

Namespaces defeat string matching; parse properly.

## Why it happens

XML namespaces and nesting make the same logical error look different as raw text. Parsers understand the structure; regular expressions do not.

## Edge cases

- Default namespaces need explicit handling; wildcard the namespace in searches.
- Faults can nest detail elements with extra structured info; read those too.
- Log the raw XML at debug level; it is the ground truth.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Q_ZB1CDL8GVAkzIninUdGQ