When a directory server answers an LDAP write request, what does the LDAPResult in that reply tell the client?

## Every message travels in the same envelope An LDAP connection carries `LDAPMessage` structures in both directions. Each one holds a **`messageID`** chosen by the client, exactly one protocol operation — an `AddRequest`, a `ModifyRequest`, a `ModifyDNRequest`, a `DelRequest`, a `CompareRequest` — and an optional `controls [0]` field. The server repeats the client's `messageID` on every message it sends in answer. That repetition is the **only** correlation the protocol gives you. A client may have several operations outstanding on one connection at the same time, and the server is free to answer them in whatever order it finishes them. Pairing a reply with a request by arrival order is a defect that behaves perfectly on a quiet test directory and misattributes results the first time two writes overlap. ## Almost every reply is the same structure The write operations do not each define a bespoke response body. Add, Modify, ModifyDN, Delete and Compare all answer with the same `LDAPResult` fields: - **`resultCode`** — an enumerated verdict. `success (0)` means the server applied the operation; every other value is the server saying why it did not. - **`matchedDN`** — filled in when the failure was one of *name resolution*. It names the deepest existing entry the server managed to resolve from the DN the client supplied. - **`diagnosticMessage`** — free text intended for a human reader. It may be an empty string, its wording differs between implementations, and nothing in the protocol constrains it. - **`referral [3]`** — present when the `resultCode` is `referral (10)`, meaning this server does not hold the named part of the tree and is pointing elsewhere. The consequence for application code is that error handling is uniform. One function reads a reply, switches on `resultCode`, and never needs to know which of the five write operations produced it. ## Reading the resultCode | resultCode | what the server is saying about a write | |---|---| | `success (0)` | the operation was applied | | `entryAlreadyExists (68)` | an Add named a DN that is already in use | | `noSuchObject (32)` | the named entry, or an ancestor of it, does not exist — read `matchedDN` | | `insufficientAccessRights (50)` | the connection's authenticated identity is not permitted to do this | | `unwillingToPerform (53)` | the server refuses on policy grounds; the request itself was well formed | | `notAllowedOnNonLeaf (66)` | a Delete named an entry that still has subordinate entries | | `compareTrue (6)` / `compareFalse (5)` | a Compare's actual answer, not a failure | The last row is the one that catches people. A Compare never answers `success (0)`; its result *is* the verdict, so code that treats every non-zero `resultCode` as an exception will report an error for a perfectly good comparison. ## matchedDN is a diagnosis, not an echo Suppose a consolidation job adds `cn=Dana Okafor,ou=Staff,dc=riverside,dc=example,dc=org` to a directory where `dc=riverside,dc=example,dc=org` was never created. The reply is `noSuchObject (32)` with `matchedDN` set to `dc=example,dc=org` — the deepest ancestor that does exist. That single field tells the client exactly which level of its assumed tree is missing, which turns a retry loop into a one-line fix: create the intermediate entries first. A client that logs only the `resultCode` throws that information away. ## What a success does and does not promise 1. **A single Modify is applied as one unit.** All of its changes take effect or none do, so a `success (0)` on a Modify means the whole change list landed. 2. **A sequence of operations is not a transaction.** Three separate requests that must all land are three separate verdicts, and the base protocol offers nothing that ties them together. A client that fails half way must be able to re-run its own work. 3. **Success means the server accepted the change as it understood it.** Values are stored under the attribute's own rules, so what comes back on a later read need not be byte-identical to what the client sent — success is a statement about acceptance, not about formatting. The practical discipline is short: correlate on `messageID`, branch on `resultCode`, read `matchedDN` when a name failed to resolve, and log `diagnosticMessage` for the human who will read the ticket — never parse it.