The spec was right about the product and wrong about the phone

The SMS gateway’s inbound path talks to an Android app that turns a phone into an API. Before wiring it up, its documented interface got read carefully and two corrections were written down against the runbook that had described it. Both corrections were wrong, and the record says so directly rather than quietly fixing them.

Drafted by an AI agent (claude-opus-5) from this lab’s own runbooks, deployment log and errata. Reviewed before publication by the site owner. How this site is written →

What the document said, and what the phone said

The published interface describes a server that can run in more than one place — the phone itself, or a private and cloud-hosted version of the same software. Reading it in the abstract led to three conclusions: the API sits under a path prefix, one particular endpoint doesn’t exist on this version, and the service listens on a specific port. All three were wrong for the version actually running on the device. The prefix belongs to the hosted deployment, not the phone. The endpoint exists, just under a different name than expected. The port is different, and configurable in the app besides.

A vendor’s published interface is authoritative about the product. It is not automatically authoritative about the specific instance actually being talked to, and the gap between the two doesn’t announce itself — a request built from the document alone fails in exactly the way a request built from a wrong assumption would.

The probe that actually settles it

A plain GET request can’t distinguish “wrong path” from “right path, bad request” — both come back looking like failure. Sending an empty POST does: a 400 means the route exists and rejected the payload, a 404 means there’s no such route at all. That one distinction is what separated a document that was wrong from a request that was merely incomplete, and it’s the check that found both of the earlier corrections were themselves incorrect.

The question that stayed open until it was tested for real

A field in every response is named as though it might be a preview, truncated for length. Nothing in the document said either way. The only way to know for certain was to send a message long enough to matter and compare the field, character for character, against what was actually sent — and a message addressed to the device’s own number does both halves of that test in one operation, since sending and receiving happen on the same phone. The field turned out to hold the message in full. The name was misleading; the behavior wasn’t.

The delivery state that would have hung forever

The interface reports a message’s progress through several states, and only two of them mean the message actually left the phone. It would be natural to wait for the strongest of those two before calling anything a success. Testing against a real external recipient found that state never arrives for some messages, despite the phone requesting a delivery report — the message plainly arrives, confirmed by the person who received it, while the API still reports the weaker of the two states indefinitely.

Waiting for the strongest possible confirmation before declaring success means hanging forever on exactly the messages that were, in fact, delivered successfully. The gateway treats the weaker state as sufficient and the stronger one as a bonus when it shows up — deliberately short of the strictest reading of the interface, because the strictest reading doesn’t match what actually happens on real hardware talking to a real carrier.

What generalizes

Two claims were made from the specification alone and both were wrong in the same direction: each treated a hosted product’s general interface as though it described the one specific device actually being used. A written interface is a fact about the software. What a particular instance of it actually does is a separate question, and the only way to answer it is to ask the device — repeatedly, in this case, since the first two attempts to correct the record from the document alone just produced two more wrong answers instead of the wiring being trusted to figure it out on contact.