Every major API provider — Stripe, Twilio, SendGrid, GitHub — maintains versioned APIs and eventually deprecates old ones. The standard promise is "we'll give you plenty of notice." The standard reality is that notice arrives as an email to a billing address nobody monitors, a blog post nobody subscribes to, and a deprecation header in API responses nobody is parsing. Production breaks anyway.
This article covers how API providers actually communicate deprecations, why those signals get missed, and what you can monitor to catch upcoming deprecations before they break you.
Stripe's API is versioned by date (e.g., 2023-10-16). When you create a Stripe account, your account is pinned to the API version current at that time. Stripe's policy is to support API versions for at least 18 months before sunsetting them, and they email the account owner before doing so.
The problem: "the account owner" is whoever set up the Stripe account. At many companies this is a founder, a contractor, or a developer who left two years ago. The email goes to billing@youroldstartup.com. Nobody reads it. Stripe also adds a Stripe-Version header and a deprecation warning to API responses starting 6 months before a version is removed — but if nobody is logging and alerting on response headers, those warnings are invisible.
Twilio announces API changes via their changelog at twilio.com/changelog, their developer newsletter, and direct emails to account holders. When specific endpoints or parameters are deprecated, they add deprecation notices to their API reference. Twilio also uses Warning headers in HTTP responses to flag deprecated parameter usage — the same missed-unless-you-parse-it problem as Stripe.
One notable Twilio deprecation pattern: SMS pricing API endpoints have changed multiple times, catching developers who built billing-related integrations directly against those endpoints. The change is documented; the documentation is not where most developers look when production breaks.
SendGrid has deprecated and removed API v2 in favor of v3. The transition was announced via blog post, migration guide, and email. Developers who built against v2 in 2018 and never touched the integration again were hitting broken endpoints in 2020. The integration "worked fine" until the day it stopped.
GitHub announces API deprecations via their developer blog and the GitHub changelog. They also use a Deprecation response header on endpoints that are scheduled for removal, with a Sunset header indicating the removal date. The GitHub GraphQL and REST APIs have both had significant deprecations — OAuth app permission scopes, repository topics endpoints, and collaborator invitation APIs have all changed in ways that broke existing integrations.
In 2018, Stripe dropped support for TLS 1.0 and 1.1, requiring TLS 1.2 or higher. This wasn't a versioned API change — it was a transport-level change. They announced it well in advance with a migration guide. Teams running old Ruby on Rails apps on older servers with outdated OpenSSL versions found out when requests started failing. The notice existed; the engineering team never mapped "Stripe TLS notice" to "our Rails 4.1 app on Ubuntu 14.04."
In 2021, GitHub removed support for password authentication to the API and to Git operations. After August 13, 2021, any script or CI pipeline using username/password authentication stopped working. GitHub sent emails and published extensively. Teams with automated scripts that hadn't been touched in years found them broken the morning of August 14th. The script owner had left the company. The email went to an unmonitored alias.
SendGrid sunset the v2 API in January 2021. Applications using https://sendgrid.com/api/mail.send.json started receiving 410 Gone responses. Teams that had set up transactional email in 2016, verified it worked, and moved on found their confirmation emails and password resets silently failing. No runtime error in the application — just 410s from SendGrid that nobody was alerting on.
The IETF standard (RFC 8594) defines Sunset and Deprecation response headers. Stripe, GitHub, and others have adopted these. Add a response middleware that checks for these headers and logs (or alerts on) their presence:
// Express middleware: log deprecation headers
app.use((req, res, next) => {
const originalJson = res.json.bind(res);
res.json = (body) => {
if (res.getHeader('Deprecation') || res.getHeader('Sunset')) {
console.warn('API deprecation notice', {
url: req.url,
deprecation: res.getHeader('Deprecation'),
sunset: res.getHeader('Sunset'),
});
}
return originalJson(body);
};
next();
});
For outgoing HTTP calls to third-party APIs, instrument your HTTP client to log these headers on responses:
// Axios interceptor
axios.interceptors.response.use((response) => {
if (response.headers['deprecation'] || response.headers['sunset']) {
logger.warn('External API deprecation', {
url: response.config.url,
deprecation: response.headers['deprecation'],
sunset: response.headers['sunset'],
});
}
return response;
});
Most provider changelogs publish RSS feeds. Subscribe in an RSS reader or pipe them to a Slack channel:
https://stripe.com/docs/changelog.rsshttps://developer.github.com/changes.atomA Slack webhook + RSS-to-webhook bridge (Zapier, n8n, or a simple cron job) means deprecation announcements appear in your #api-deprecations channel the moment they're published.
For Stripe specifically: log in to the Stripe dashboard, go to Developers → API keys, and check your account's pinned API version. If it's more than 18 months old, you're in the deprecation window. Do the same with any other provider that exposes version information in their dashboard.
For critical integrations, write a canary test that calls a known endpoint and checks for a non-4xx response. Run it on a schedule. If the endpoint is deprecated and eventually removed, your canary alerts before production traffic is affected:
# A synthetic monitor in pseudocode
GET https://api.stripe.com/v1/charges?limit=1
Assert: status != 410 and status != 404
Assert: no 'Deprecation' header present
Alert: on failure or deprecation header presence
APIWatch monitors your third-party API integrations for deprecation signals — Sunset headers, version warnings, changelog announcements — and alerts you via Slack or email before the removal date. Stop learning about deprecations from production outages.
Join the APIWatch waitlist →← All articles · APIWatch · API deprecation monitoring tools comparison