by Serguey Shinder
In October 2023 a purchasing manager at one of our trade customers rang to ask why nothing she had ordered from us in four days had arrived. As far as her system was concerned, nothing had been sent at all.
It had been sent, and it had been answered. Nine of her order lines asked for more of a product than we held, and our ordering interface replied, as it had for eight years, with a refusal. What had changed was the wording. The old message said Insufficient stock for item, followed by the product code. A colleague in our customer team had asked, reasonably, for something less abrupt, and I had changed it to We are unable to supply the full quantity of this item at present. The ticket took twenty minutes. Nobody reviewing it could have thought it mattered, and nobody did.
Her purchasing system had been written by a contractor in 2016. When a response contained the words Insufficient stock, it moved the line to her second supplier. Anything else it filed as an unknown fault, in a queue that somebody was supposed to check and in practice checked on Fridays. Two other customers had built something similar. One of them matched on the whole sentence, full stop included.
I was annoyed for an hour. Then I read our documentation, which said nothing about the text of our messages. The contractor had guessed, and the guess was sensible, because there was nothing else to go on. Our responses carried a status and a sentence. The status said something had failed. Only the sentence said what. We had published exactly one way for a program to tell a stock shortage from a malformed order, and it was written in English for a human being.
That was the part I had wrong. I thought of the message as presentation, like the colour of a button, and presentation is ours to change. But anything a program can receive, some program will eventually depend on, and a program cannot tell a sentence somebody polished from a sentence that now means something new. Give integrators nothing stable to hold and they will hold whatever is there.
We put the old sentence back the same afternoon. Then every error our interface can return was given a short code, stock_short, price_changed, account_on_hold, thirty seven of them in all, listed in the documentation with a promise that a code will never change meaning and never disappear without six months' notice. The message beside it is documented, in writing, as text for people, free to change without warning. We asked every customer with an integration to switch, and most had within a year.
The sentence has been reworded twice since. Nobody rang, which is the only evidence I trust that it is finally free to say whatever it likes.
– Serguey Asael Shinder
Leave a Reply