The outage started with a 404 on what had been a perfectly stable endpoint for two years. Stripe had deprecated /v1/charges in favor of /v1/payment_intents — and had announced it in their changelog 90 days before the cutoff. One email, one changelog entry, and then silence until the day the old endpoint stopped accepting requests.
By the time anyone noticed, 47 orders had failed silently over six hours. The monitoring that caught it was a customer calling support.
This is the standard deprecation story. Here's why it happens, and what you can do to catch it before the Thursday outage.
Most API providers announce deprecations via email to the account owner. That email goes into the inbox of whoever created the API key — often a developer who left six months ago, or a shared engineering alias that nobody monitors. The email is correct, the notice period is reasonable, and nobody reads it.
The Sunset header (RFC 8594) and the Deprecation header are designed specifically for this problem: the API provider adds them to responses to signal that an endpoint is going away on a specific date. Here's what they look like:
HTTP/1.1 200 OK
Deprecation: Sun, 01 Dec 2026 00:00:00 GMT
Sunset: Sun, 01 Jan 2027 00:00:00 GMT
Link: <https://api.example.com/v2/orders>; rel="successor-version"The headers are there. They're in every response from the deprecated endpoint. But virtually nobody parses response headers in their API integration code — you extract the JSON body, check the status code, and move on. The deprecation signal sits in the headers unread until the endpoint stops working.
Not every API uses explicit version headers or sunset dates. Some APIs just change behavior: a new required field is added, an optional field becomes required, a field is renamed, an enum value is removed. These changes don't generate 404s — they generate 400s or malformed responses that look like client errors, not deprecations.
Stripe, Twilio, GitHub, and most serious API providers maintain detailed changelogs. The problem isn't the announcement — it's the discovery model. You don't subscribe to a changelog and get push notifications the moment something changes that affects your integration. You have to go check. Nobody does this on a weekly basis across every API they use.
The failure modes are less obvious than "endpoint disappears":
| Breaking change type | How it manifests | How hard to detect |
|---|---|---|
| Endpoint removed | 404 or 410 | Easy — monitoring catches it |
| New required field | 400 with validation error | Medium — looks like a client bug |
| Response field removed | Null pointer / parsing error | Hard — surfaces as your bug, not theirs |
| Rate limit change | 429 at previously-safe volumes | Hard — intermittent, load-dependent |
| Auth method deprecated | 401 on what was a valid request | Medium — clear signal, unclear cause |
| Behavior change, same response shape | Wrong data, no error | Very hard — requires business logic validation |
The dangerous ones are the last two. Response shape changes that produce valid JSON with wrong values — a field that used to be a UNIX timestamp now returns an ISO 8601 string, an amount that used to be in dollars now returns cents — produce no errors at all. They produce incorrect orders, billing failures, or corrupted data that you find in a spreadsheet three months later.
The major providers have machine-readable changelogs:
If you use RSS: most changelogs publish feeds. Pipe them into Slack via an RSS bot. This gets you push notifications, but you still have to read them and understand which changes affect your integration.
The highest-signal detection you can add today: check every API response for Sunset and Deprecation headers in your HTTP client layer. Here's a Node.js/axios interceptor that does this:
// api-deprecation-monitor.js
const axios = require('axios')
const nodemailer = require('nodemailer')
const ALERT_EMAIL = process.env.ALERT_EMAIL
const SMTP_URL = process.env.SMTP_URL
// Add a response interceptor to every axios call
axios.interceptors.response.use(
async (response) => {
const sunset = response.headers['sunset']
const deprecation = response.headers['deprecation']
if (sunset || deprecation) {
const url = response.config.url
const sunsetDate = sunset ? new Date(sunset) : null
const daysUntilSunset = sunsetDate
? Math.ceil((sunsetDate - Date.now()) / 86400000)
: null
// Log to console always
console.warn('[API DEPRECATION DETECTED]', {
url,
deprecation,
sunset,
daysUntilSunset,
successor: response.headers['link'],
})
// Send email alert
if (ALERT_EMAIL && SMTP_URL) {
await sendDeprecationAlert({
url,
deprecation,
sunset,
daysUntilSunset,
successor: response.headers['link'],
})
}
}
return response
},
(error) => Promise.reject(error)
)
async function sendDeprecationAlert({ url, deprecation, sunset, daysUntilSunset, successor }) {
const transporter = nodemailer.createTransport(SMTP_URL)
const urgency = daysUntilSunset !== null && daysUntilSunset < 30 ? '🚨 URGENT' : '⚠️'
await transporter.sendMail({
from: process.env.ALERT_FROM || 'alerts@yourapp.com',
to: ALERT_EMAIL,
subject: `${urgency} API deprecation detected: ${new URL(url).hostname}`,
text: [
`Endpoint: ${url}`,
deprecation ? `Deprecation date: ${deprecation}` : '',
sunset ? `Sunset date: ${sunset}` : '',
daysUntilSunset !== null ? `Days until sunset: ${daysUntilSunset}` : '',
successor ? `Successor: ${successor}` : '',
'',
'This endpoint is scheduled for removal. Update your integration before the sunset date.',
].filter(Boolean).join('\n'),
})
}
module.exports = { axios }
Use this in your codebase by importing axios from this module instead of directly from the package. Every API call you make will automatically check for deprecation headers.
Environment variables: ALERT_EMAIL (where to send alerts), SMTP_URL (e.g. smtp://user:pass@smtp.gmail.com:587), optionally ALERT_FROM.
For your highest-stakes integrations, run a synthetic check every hour: hit the endpoint with a known-good request and validate the response shape, not just the status code. If the response shape changes — a field disappears, a type changes — your test fails before production traffic fails.
// synthetic-monitor.js — run hourly via cron or a job scheduler
const { axios } = require('./api-deprecation-monitor')
async function checkStripeEndpoint() {
// Use a real but low-stakes request
const response = await axios.get('https://api.stripe.com/v1/balance', {
headers: { 'Authorization': `Bearer ${process.env.STRIPE_SECRET_KEY}` }
})
// Validate expected response shape
const { available, pending } = response.data
if (!Array.isArray(available) || !Array.isArray(pending)) {
throw new Error(`Unexpected response shape: ${JSON.stringify(Object.keys(response.data))}`)
}
console.log('Stripe balance endpoint: OK')
}
checkStripeEndpoint().catch((err) => {
console.error('Synthetic check failed:', err.message)
// Send alert (reuse the same alert function)
process.exit(1)
})
on: schedule: - cron: '0 * * * *') runs your monitor without any new infrastructure. GitHub Actions sends you an email when a workflow fails.
The interceptor catches Sunset/Deprecation headers — but only for providers that emit them. Most don't. GitHub, Twilio, and Stripe do for some endpoints. Many smaller APIs don't implement RFC 8594 at all.
The synthetic monitor catches shape changes — but only for endpoints you explicitly test. A typical app touches dozens of API endpoints, and you realistically only write synthetic tests for the critical path.
And neither approach covers the changelog monitoring problem: knowing that something changed across 50+ APIs that your codebase depends on, translated into plain English, before you have to go read each provider's changelog manually.
APIWatch monitors changelogs for 50+ major APIs — Stripe, OpenAI, Twilio, GitHub, Slack, and more — and sends plain-English alerts the moment a breaking change or deprecation is announced. Know 30 days before your app does.
Early access pricing for waitlist members.
Join the APIWatch waitlist →Sunset header spec: RFC 8594. Provider changelogs linked above were current as of September 2026.