When the Model Survives but One Parameter Expires: A Dated Deprecation Calendar for Claude API Requests

Decomposing a request into parts

Next, extract the set of parts from the request you are about to send. This is a plain mapping; the only thing that matters is that nothing is missed.

interface OutgoingRequest {
  model: string;
  params?: Record<string, string | number | boolean>;
  betaHeaders?: string[];
}
 
function decompose(req: OutgoingRequest): RequestPart[] {
  const parts: RequestPart[] = [{ kind: "model", value: req.model }];
 
  for (const [k, v] of Object.entries(req.params ?? {})) {
    parts.push({ kind: "param", value: `${k}=${v}` });
  }
  for (const b of req.betaHeaders ?? []) {
    parts.push({ kind: "beta", value: b });
  }
  return parts;
}

Decide part equality on kind and value alone. Normalizing to strings lets you use set operations directly.

const partKey = (p: RequestPart) => `${p.kind}:${p.value}`;
 
// Does req contain every part of entry.when?
function matches(reqParts: RequestPart[], entry: DeprecationEntry): boolean {
  const have = new Set(reqParts.map(partKey));
  return entry.when.every((w) => have.has(partKey(w)));
}

Separating warning from stopping, before the run

This is the center of the design. A part that has not yet reached its sunset date warns you how many days remain; a part already past its date stops the run itself. Call the former warn-ahead and the latter fail-on-date.

type Verdict =
  | { level: "ok" }
  | { level: "warn"; daysLeft: number; entry: DeprecationEntry }
  | { level: "expired"; entry: DeprecationEntry };
 
const DAY = 24 * 60 * 60 * 1000;
 
function evaluate(
  req: OutgoingRequest,
  now: Date,
  warnWindowDays: number,
): Verdict[] {
  const parts = decompose(req);
  const verdicts: Verdict[] = [];
 
  for (const entry of DEPRECATION_CALENDAR) {
    if (!matches(parts, entry)) continue;
 
    // A timezone-bearing string resolves to a correct absolute (UTC) instant
    const effective = new Date(entry.effectiveAt).getTime();
    const diff = effective - now.getTime();
 
    if (diff <= 0) {
      verdicts.push({ level: "expired", entry });
    } else if (diff <= warnWindowDays * DAY) {
      verdicts.push({ level: "warn", daysLeft: Math.ceil(diff / DAY), entry });
    }
  }
 
  if (verdicts.length === 0) verdicts.push({ level: "ok" });
  return verdicts;
}

new Date(entry.effectiveAt) resolves a timezone-bearing ISO string to an absolute UTC instant internally — which is exactly why writing the zone into effectiveAt pays off. Keep only a date here and the comparison against now is dragged into the runtime's local time, so the verdict wobbles for half a day around the boundary.

Place the check at the entry point of the run. Under unattended operation, it is safest to log warnings and continue, but stop on expiry immediately so a human notices.

function preflight(req: OutgoingRequest, warnWindowDays = 14): void {
  const verdicts = evaluate(req, new Date(), warnWindowDays);
 
  for (const v of verdicts) {
    if (v.level === "warn") {
      console.warn(
        `[deprecation] expires in ${v.daysLeft}d: ${JSON.stringify(v.entry.when)} → ${v.entry.migrateTo} (source: ${v.entry.source})`,
      );
    } else if (v.level === "expired") {
      // Stop clearly, before the call
      throw new Error(
        `[deprecation] expired request part: ${JSON.stringify(v.entry.when)}. Migrate to: ${v.entry.migrateTo} (source: ${v.entry.source})`,
      );
    }
  }
}

The caller adds a single line.

function runScheduledBatch(req: OutgoingRequest) {
  preflight(req);          // throws here on expiry, without hitting the API
  // …the actual Messages API call…
}

The effect of that one line is understated but reliable. The moment a sunset date passes, it stops with a message that names the migration target, without ever emitting a wasted 400. No time is spent decoding the error afterward.

Choosing the warn-ahead window from operational feel

How many days warnWindowDays should be depends on how often you revisit your logs. Honestly, I do not look at my sites' auto-posting every day. I check in batches every few days, so too short a window produces the "already past it by the time I noticed" failure.

I keep it at 14 days now. Since adopting that width, the reactive scramble of fixing a batch only after it stopped on the sunset date has disappeared. I used to learn about an expired model or parameter for the first time from an error log about once a month. Since the startup warning began flagging these ahead of time, that miss rate has held at zero.

Make the window too long and warnings fire on every run while everything still works, until the warning itself fades into background noise. "Two to three times your review cadence" is a good target: it guarantees room to act when a warning appears, without ringing constantly.

A CI test so the calendar never rots

The weakness of this design is obvious — if a human forgets to append to the deprecation calendar, none of it matters. So guard the calendar's own health in CI. Two things are worth protecting: that you cannot merge a live config carrying an already-expired row, and that every calendar row at least carries a source.

import { test, expect } from "vitest";
 
// The configs your scheduled tasks actually send (make it reflect production truth)
import { LIVE_REQUESTS } from "./live-requests";
 
test("no live request carries an expired part", () => {
  const now = new Date();
  for (const req of LIVE_REQUESTS) {
    const verdicts = evaluate(req, now, 0);
    const expired = verdicts.filter((v) => v.level === "expired");
    expect(
      expired,
      `an expired config remains: ${JSON.stringify(req)}`,
    ).toHaveLength(0);
  }
});
 
test("every calendar row carries a source and a migration target", () => {
  for (const entry of DEPRECATION_CALENDAR) {
    expect(entry.source.length).toBeGreaterThan(0);
    expect(entry.migrateTo.length).toBeGreaterThan(0);
  }
});

The first test targeting the actually-running configs, LIVE_REQUESTS, is the point. Verifying the calendar in the abstract means nothing if production configs do not follow it. If a live config still carries an expired row, CI goes red right then, and a deploy that crosses a sunset date is stopped. The official docs do not cover how to fold a deprecation notice into your own code. These two tests are the minimum way to move that folding from human memory into machinery.

Where to start

If you have processes running unattended, the safe start is to slot only decompose and evaluate in front of an existing call and emit warn-level logs alone. Turning on the stop is worth doing only after you have written one real deprecation notice into the calendar and confirmed the test goes red on that date as expected.

If you already have a mechanism watching for model retirement, layer this part-level watch on top of it. A slip like this one — the model alive while a single part dies — can then be closed at the same entry point, together.

If it removes one quiet miss for anyone else running several automated jobs, I will be glad. Thank you for reading.