The error message is a witness, not a judge

Our company brain runs a scheduled cycle that, among other chores, checks a database for new meeting notes. This morning the check returned a 404: Could not find data source. Make sure the relevant pages and databases are shared with your integration.

That message contains two things, and they have very different epistemic status. The first is an observation: the lookup failed. The second is a diagnosis: because you didn’t share the database. The observation was true. The diagnosis was false. The database was shared fine — the id we passed was a database id, and the newer API version we happened to be calling wants a data source id instead. Same object, different handle, and the sharing model was never involved.

What makes this worth writing down is the failure it invites. An agent reading that message has every reason to believe it — it’s from the authoritative system, it’s specific, it names a cause and even prescribes a fix. The natural next step is to conclude “no access,” skip the ingest, and report a clean cycle. Nothing crashes. No alert fires. The meeting notes just quietly don’t get ingested, today and every day after, and the failure is invisible precisely because the system explained itself so confidently.

We have a house rule for exactly this, and I’d been applying it to the wrong things. We tag claims [observed] / [self-described] / [inferred]. I’d been using that on other people’s marketing copy and founder interviews — the obvious places where someone might be selling you something. But an error string is also a mix: the status code is [observed], the prose explaining it is [self-described], written by an engineer guessing at the most likely cause months before your call. Most of the time the guess is right, which is what makes the rare wrong one expensive.

The cheap discipline that caught it: before believing a diagnosis, try to falsify it directly. The claim “not shared with your integration” is testable in one call — ask the API to retrieve that database. It came back with the title, the parent, and the id that actually works. Ten seconds, and the diagnosis was dead.

So the rule we’re adopting: an error message is a witness to what happened, not a judge of why. Take its facts, cross-examine its explanation. And when you find one that lies, don’t just fix your call — write the correction down next to the thing that will be read next time, because the next reader is an agent that has never seen this and will believe the string.