Your SDK is three versions behind your API when a customer opens a ticket asking why a field your docs describe doesn't exist in the TypeScript client, and the honest answer is: nobody regenerated the SDK after the last four API releases. That gap is called SDK drift, and it happens quietly — the API ships, the SDK repo doesn't, and the distance grows until a support ticket forces someone to notice. The fix is not a heroic manual sync. It's a diff between your spec and your SDK's actual surface, followed by a pipeline that regenerates on every spec change so drift can't accumulate again.
How SDK drift happens
Drift isn't one mistake. It's a maintenance model that has no forcing function.
The SDK lives in its own repo, on its own clock. Most teams start their SDK as a hand-written or semi-generated client in a separate repository from the API. The API team ships a new endpoint Tuesday; the SDK repo has no CI hook that knows that happened. Someone has to remember to open a PR.
Regeneration is a manual, skippable step. Even teams using a codegen tool often run it by hand: pull the spec, run the generator, diff the output, decide what to publish. Each step is a place work gets deferred when the sprint is busy — and busy sprints are exactly when APIs change fastest.
Nobody owns "SDK is current" as a metric. API teams are measured on API correctness. SDK teams, when they exist, are usually the same people, stretched thin. There's no dashboard that goes red when the SDK's method list falls behind the spec's operation list, so the gap is invisible until a customer hits it.
Multiple languages multiply the problem. A TypeScript SDK one version behind is bad. TypeScript, Python, and Go SDKs each behind by a different amount is worse, and it's the default state for any team maintaining more than one language by hand.
What SDK drift actually costs
The cost shows up in three places, and none of them are visible until they're expensive.
Support tickets that shouldn't exist. "Your docs say this field exists but I get a TypeScript error" costs your support team a triage cycle and costs the customer trust, for a problem that has nothing to do with their code.
Integration bugs that look like customer error but aren't. A customer calls an endpoint your API added last month using a hand-rolled fetch call, because the SDK has no typed method for it yet. Now they're maintaining a workaround your SDK was supposed to make unnecessary.
Trust erosion that outlasts the fix. Once a customer catches the SDK lying about the API's shape, they stop trusting the types and start double-checking against raw docs — defeating the point of a typed client. That habit persists even after you catch up.
How to diagnose SDK drift
You don't need to read a changelog by hand. Diff the spec against the SDK's actual surface and let the diff tell you where they disagree.
- Pull your current OpenAPI spec — the one your API actually serves, not the one in a wiki page that hasn't been touched since Q1.
- Pull the SDK's public surface — every exported method, its parameters, and its return type, for each language you ship.
- Diff the two. For every operation in the spec, is there a matching SDK method? For every required parameter, does the SDK require it? For every response field, does the SDK's return type expose it?
- Bucket the results: missing methods (spec has it, SDK doesn't), stale methods (SDK has it, spec no longer does), and mismatched shapes (both have it, but the parameter or response type disagrees).
That's the same three-bucket structure a compatibility report uses when comparing two SDK versions against each other — here you're comparing the SDK against the spec instead. If you want this done for you instead of building the diff script yourself, Sourced's OpenAPI diff tool runs this comparison and flags exactly which operations your SDK hasn't caught up to.
The fix: a generation pipeline with drift checks
Manual regeneration is the root cause, so the fix has to remove the manual step, not just do it more diligently.
Generate from the spec, every time. Don't hand-edit generated SDK code. If you find yourself patching a generated file, that patch will get silently overwritten or silently missed on the next run — either way, it's technical debt with a fuse.
Wire regeneration into your spec's CI, not your SDK's release calendar. The trigger for "regenerate the SDK" should be "the spec changed," not "someone remembered on release day." That's the difference between drift that can't accumulate and drift that accumulates until someone notices.
Run a diff before every publish, not after a complaint. A pre-publish diff between the last-shipped SDK and the newly generated one — the kind covered in SDK compatibility reports, explained — turns "did anything break" from a guess into a report you read in five minutes.
Treat every language the same way. If TypeScript is generated and Python is hand-maintained "for now," Python will drift first and worst. Either generate all of them from the same pipeline, or be explicit that Python is a second-class citizen and set expectations accordingly.
Sourced's SDK generator builds this pipeline for you: connect a repo or upload a spec, and it regenerates TypeScript and Python SDKs with every spec change, with a compatibility report attached before anything publishes. You can create hosted docs and an SDK preview from your repo free, with no credit card, and see what your current drift actually looks like before deciding what to automate.
Honest scope: when drift isn't worth fixing with tooling
If your API changes twice a year and you have one SDK consumer who is also your own frontend team, a generation pipeline is more infrastructure than the problem deserves. Open a PR by hand when the spec changes, and move on — see the real cost of a hand-maintained client for where that math tips over. Pipeline investment pays off when you have external customers, multiple languages, or an API that changes weekly; it's overhead if none of those are true yet.
FAQ
How do I know if my SDK is out of date with my API?
Diff your OpenAPI spec's operations against your SDK's exported methods. If any spec operation has no matching SDK method, or a required field isn't required in the SDK's types, you have drift. Sourced's OpenAPI diff tool automates this comparison.
Is SDK drift always the SDK team's fault?
No — it's usually a process gap, not a person. If regeneration depends on someone remembering to run it, drift is a matter of when, not if. The fix is a pipeline trigger tied to the spec, not more diligence from the same person.
Does drift happen even with generated SDKs?
Yes, if generation runs occasionally by hand rather than being wired into CI. A generated SDK regenerated quarterly can drift as far as a hand-written one patched quarterly — the generator alone doesn't remove drift, automation does.
Should I regenerate on every spec commit or on a schedule?
On every spec commit, if you can. A schedule (nightly, weekly) still lets drift accumulate for the length of the interval. Commit-triggered generation is the only version that guarantees zero accumulated drift.
Will fixing drift once prevent it from coming back?
Only if you also fix the process that created it. Regenerating your SDK today closes the current gap; it does not stop the next spec change from reopening it unless generation is wired into your pipeline going forward.
Related reading
Once your SDK is current, the next questions are usually cost and language coverage: the real cost of a hand-maintained API client, what to do when customers ask for a Python SDK, and what to do when your docs platform has a spec but no SDK. For catching breaking changes before customers do, see detecting breaking changes in OpenAPI.