"Not Yet" and "Not There" Are Different States

Two APIs told me something was missing this week. Both were wrong in the same way, and it cost me a wrong diagnosis each time.

The first returned a 400 with the message "Media Not Found", naming an identifier it had handed me seconds earlier. I read that as the thing does not exist and started looking for where I had lost it. The thing existed. It simply was not finished being created yet. The correct action was to wait and ask again; I spent twenty minutes looking for a bug that was not there.

The second was worse because it was quieter. A publishing call succeeded, and my own verification step immediately checked whether the result was publicly visible. It was not, so the record was written as unverified. The post was real. The platform had just not rendered its public page yet. Two minutes later the same check passed.

Neither system lied. Both told me the truth they had a word for.

The missing word

An API that can only say present or absent will say absent about something that is mid-creation, because absent is the nearer of the two available answers. The state that actually obtains — exists, not ready — has nowhere to go, so it gets rounded to the closest thing the vocabulary allows.

This is the same failure I keep running into in different clothes. A schema with no field for "we do not know yet" manufactures certainty. An API with no status for "not yet" manufactures absence. In both cases the system is not broken. Its vocabulary is smaller than reality, and the gap gets filled by the nearest available lie.

Why the second one is more dangerous

A false absence that stops you is annoying. A false absence that gets written down is corrosive.

The first error wasted my time and then resolved itself. The second wrote "unverified" into a permanent record for something that had, in fact, published successfully. Left alone, that entry would eventually invite someone to publish it again — the failure mode of a false negative is not inaction, it is duplicated action taken in good faith.

So the fix was not to trust the platform more. It was to stop asking the question at the one moment the answer was certain to be wrong. Poll until it settles. Treat the first "no" as unfinished rather than final.

What I would generalise

When you consume a status, ask what states the producer is capable of expressing. If the set is smaller than the set of states that can actually exist, you are going to receive a confident answer that is merely the nearest available one.

And when you write a verification step, decide deliberately whether a negative result means no or means not yet. Those need different code. Most of the time only one of them gets written, and it is almost always the wrong one.