What does it mean for an API method to be safe?

Safe means calling it changes nothing that a caller can observe on the server. Read the state before, read the state after, and the two are identical: the method reports rather than acts, so a caller may send it as often as it likes, a shared cache may answer it without troubling the origin, and a crawler may follow it into every corner of the service. Safety is a claim about effects, not about the shape of the answer and not about the verb the method happens to be named after.

Take a method that returns one order. Before the call, order 4471 has one row in the orders table, its status reads paid, and the customer's balance is 120.00. Call the method three times in a row and look at those same three facts after each call.

Put $n$ equal to one in the first line and the second line follows immediately, so every safe operation is repeatable at no extra cost. The converse does not hold, and that gap is exactly where the usual confusion lives: repeatability asks only whether a second call differs from a first, while safety asks whether the first call did anything at all.

Deleting is the clean counterexample. Send the delete for order 4471 twice. The first call takes the table from one row to zero, the second leaves it at zero, the third leaves it at zero again. The state after two calls equals the state after one, so the operation is repeatable. It is plainly not safe, because one row became none. Replacing an order wholesale behaves the same way: the second call writes identical bytes over identical bytes, so repeating costs nothing extra, and yet the first call rewrote everything. That a second call returns 404 instead of 200 changes nothing about the state, and the property is about the state.

So what does the extra word buy, given that retry is already free for anything repeatable? Safety buys the things that need a guarantee about the first call. A shared cache may serve one response to a thousand callers, a prefetcher may issue the call on speculation, a proxy may collapse a hundred in-flight requests into one, and a crawler may walk the whole surface. None of those is legitimate for a method that deletes an order, even though deleting twice is harmless.

Where neither property holds, the caller's retry becomes a gamble, and at volume the gamble always loses. Suppose one request in a thousand reaches the server, is carried out, and is never acknowledged, and that the caller retries every such timeout. The chance a given request produces no duplicate is $1 - 0.001 = 0.999$. Over ten thousand requests a day the chance that none of them duplicates is $0.999^{10000}$. Since $\ln 0.999 = -0.0010005$, that is $e^{-10.005} \approx 0.0000452$, so the chance of at least one duplicate in the day is $1 - 0.0000452 = 0.99995$, about 99.995 per cent. Scale down to a hundred requests a day and the same arithmetic gives $0.999^{100} \approx e^{-0.10005} \approx 0.9048$, which is still a 9.5 per cent chance of a duplicate every day.

Safety is a promise about the state the API exposes, not about every byte the machine touches. A read still writes a log line, bumps a rate-limit counter, and may fill a cache; none of those is the resource the caller asked about, and a caller who leans on them is leaning on something safety does not cover. Nor does it say anything about cost or freshness: a read can be the most expensive call in the service, and the licence to repeat it is a licence the caller exercises against your capacity, so quotas and staleness are separate problems that safety leaves untouched.

The commitment runs one way. Adding a side effect to a method that was safe, a counter that appears in a listing, a message that goes out, breaks caches, prefetchers, and every retry layer that trusted the label, and it breaks them without any change to the signature or the name. That is why the classification belongs to the design rather than to the documentation: it is decided by what the code does, and once given it is a compatibility promise.