Blog
API Versioning for Public SDKs
Put the version in a header or a path and return a stable error when it is gone. Developers should not discover a breaking change as an HTML 404 from a load balancer.
2026-09-10 · 7 min read · AethelLayer
One version field, documented
A path prefix or a single header. Not both, unless one is an alias you are removing. The SDK should set it. The error should echo the version you received and the versions you still serve.
An unversioned URL that changes shape is how every SDK on old lockfiles breaks on the same morning.
Sunset before you 410
Send a Sunset or Deprecation header while the old version still works. Then reject it with a code such as API_VERSION_SUNSET and a link to the migration note. A bare 404 looks like a typo in the path.
Keep the old error body in JSON. An HTML page from the edge proxy will be parsed as a client bug.
The SDK error should match the HTTP error
If the server says API_VERSION_SUNSET, the thrown error code is API_VERSION_SUNSET. Renaming it inside the SDK splits your docs from their catch blocks.
Include the SDK version on the probe as well. A new major of the SDK pointed at an old default host is a packaging bug.
Migrate the sample in the same release
The quickstart, the changelog, and the default in the SDK move together. Leaving the README on the sunset version manufactures the tickets.
Cluster probes by the version string. One issue per retired version is enough.
Keep reading
Capture the failure before they leave
Capture the failure before they leave. Book early access or talk to sales, then install @aethellayer/sdk when you are onboarded.