In the spring our returns team noticed that one postal region had a failed delivery rate four times everyone else's. The drivers' notes said the same thing in different words: no such flat, building name only, address incomplete. The addresses in our system were complete. The addresses on the labels were not.
Our carrier's booking API accepts an address as four lines. We send them from our checkout form, which has a single free text line for the first part and is used by customers in new build developments with names like Apartment 214, The Printworks, Riverside Quarter. That is forty eight characters. The carrier's documentation, in a table on page nine of a PDF, limits each line to thirty five. Their API does not reject a longer value. It returns 201, stores the first thirty five characters, and prints those on the label. Our integration tests used addresses from a fixture file, all of them short.
About three percent of our parcels had at least one line over the limit, concentrated where developments give flats long names. We had been paying redelivery fees on some of them for a year and a half.
The fix has three parts. Before booking we validate against the carrier's own field limits, which now live in a small typed profile per carrier alongside their timeouts and character set, and a line that is too long is rebalanced across the four lines at word boundaries, falling back to a manual review queue if it still does not fit. After booking we read the shipment back from their API and compare the stored address with what we sent, recording any difference as a metric per carrier and field, because a silent truncation is only visible from their side of the interface. And the checkout form tells customers when the first line is long enough to be split, which reduced the problem at source more than anything clever did.
The difference metric found two more quiet transformations in its first week: one carrier strips accented characters from names, and another uppercases everything and drops apostrophes, which did not matter until it did for a street in Wales.
A 201 means the other system accepted your request. It does not mean it kept what you sent, and the only way to know is to ask it for the record back.
– Sergey Shinder
