Forward compatibility and fault tolerance in TypeScript API Clients/SDKs

Summary

SDKs TypeScript forward compatibility and fault tolerance David Adler December 1, 2025 - 6 min read SDKs As an end-user of an SDK, one of the most confusing experiences is receiving a 200 response from the server but also getting an error from the SDK. How can both things be true at the same time? This happens more often than you might think, and there are two main causes: API evolution and inaccurate OpenAPI specs. When an API adds a new enum value, extends a union type, or doesn’t return a required field, SDKs with strict validation will reject the response even though the server successfully processed the request. Server-side solutions There are several approaches API providers can take to prevent these issues on the server side. One option is to tag clients with a version of the API and never send back schemas that could break older clients. Another approach is to add a validation layer on the server, generate specs from the implementation, or use a generated backend adapter layer. Contract testing can also help catch breaking changes before they reach production. However, not all API backends have the discipline or hygiene to implement these solutions perfectly. Even when they do, it’s not always practical to version every response, and in many cases it makes more sense for the client to handle API evolution gracefully rather than requiring the server to maintain perfect backward compatibility forever. Client-side solutions Speakeasy SDKs provide several features to handle API evolution gracefully on the client side. These features ensure that your SDK continues to work even when the API evolves, without sacrificing type safety or developer experience. Forward-compatible enums Enums are one of the most common sources of breaking changes. When an API adds a new status, category, or type value, SDKs with strict enum validation will reject the entire response. Forward-compatible enums are enabled by default for new TypeScript SDKs. You can also configure this expl...