An AI Vendor's API Deprecation Forced a Scramble We Should Have Planned For

Ninety days' notice for an API deprecation sounds like plenty of runway until you actually start the migration and discover how much of your system quietly assumed the old response shape would exist forever. We had three sprints to move a production classification pipeline off a deprecated endpoint, and we spent most of the first sprint just finding everywhere it was referenced.

Why it took longer than it should have

The pipeline wasn't calling the vendor's API from one clean module — it had crept into four different services over eighteen months, each written by someone who reasonably just called the API directly rather than going through a shared client, because at the time there was no shared client to go through. There was no single place to change the integration. There were four places, each with slightly different error handling for the same vendor.

A ninety-day deprecation notice is generous for a well-abstracted integration and barely enough for one scattered across four services, and you don't find out which one you have until the notice arrives.

What we did under pressure

• Built a thin adapter layer that normalized the old and new response shapes behind one interface, even though it would have been cheaper to build before the deprecation than during it.
• Migrated the highest-traffic service first and ran it in parallel with the old endpoint for a week to compare outputs before cutting over the rest.
• Discovered one of the four call sites had a subtle retry bug that only the deprecation forced us to finally look at.

We made the deadline, but only because the team dropped other client work for two weeks. The actual fix — the adapter layer that should have existed from day one — is now a standing requirement on every new vendor integration I scope, regardless of how stable the vendor seems. Every vendor seems stable until the deprecation email arrives.