[Bug]: Unexpected API change (new 'BLOCKED' state) breaks backward compatibility and causes runtime Zod errors in older SDK versions

[RodrigoTomeES]

Recently, our production SaaS application went down without any code changes on our end. This happened because the Vercel API started returning a new state and readyState value (BLOCKED) for deployments.

Because the Vercel SDK uses strict Zod enum validation for the deployment state, our installed version of the SDK threw a runtime exception when parsing the response, effectively breaking our application.

This is the second time an unannounced breaking change in the underlying Vercel API has broken our production environment due to strict validation in the SDK. It is highly frustrating to wake up to a broken product when no deployments or changes were made on our side.

Error Log

Here is the runtime error caused by the library failing to parse the new API response in the method await vercel.deployments.getDeployments({ teamId: teamId, projectId: vercelProjectName });:

[cause]: Error [ZodError]: [
    {
      "code": "invalid_union",
      "unionErrors": [
        // ... omitted some output for brevity
        {
          "issues": [
            {
              "received": "BLOCKED",
              "code": "invalid_enum_value",
              "options": [
                "BUILDING",
                "ERROR",
                "INITIALIZING",
                "QUEUED",
                "READY",
                "CANCELED",
                "DELETED"
              ],
              "path": ["deployments", 5, "state"],
              "message": "Invalid enum value. Expected 'BUILDING' | 'ERROR' | 'INITIALIZING' | 'QUEUED' | 'READY' | 'CANCELED' | 'DELETED', received 'BLOCKED'"
            }
          ],
          "name": "ZodError"
        }
      ],
      "path": ["deployments", 5, "state"],
      "message": "Invalid input"
    },
    // ... same error repeats for "readyState"
]

Expected Behavior

• APIs should ideally maintain backward compatibility. If a new enum value is added to the API, older SDK versions shouldn't crash entirely. The SDK should handle unknown states gracefully rather than failing strict validation and taking down the consuming application.

• Breaking API changes should be communicated transparently.

Questions regarding workflow and updates

Since we need to ensure our SaaS remains stable, I would like to ask for guidance on how we should consume this SDK:

• Communication: Is there a specific mailing list, changelog, or status page where these API changes (like adding new deployment states) are announced before they are deployed? This would allow us to adapt our code in advance.

• Release Cadence: Are new SDK versions released to support these API changes before the API changes actually go live in production?

• Recommended Workflow: What is Vercel's recommended workflow to prevent these runtime errors? Are we expected to constantly set up automated jobs to update the Vercel SDK to the latest version to avoid our production app from breaking?

We love using Vercel, but we need a reliable way to interact with the API without the fear of strict validation breaking our app unexpectedly. Thank you for your time and help.

[ismaelrumzan]

Hello @RodrigoTomeES
Thanks for reporting and apologies for the breaking changes.
You can view all releases here: https://github.com/vercel/sdk/releases
Regarding the cadence, the SDK is regenerated within 24-48 hrs of changes in the API code going live
We use https://www.speakeasy.com/ for generating the SDK from our REST API. We are going to look into enabling a "forward compatibility" feature to allow backward compatibility moving forward. However, that will require an period of auditing before we can release it.
How do you currently update the SDK version?

[RodrigoTomeES]

Hello @ismaelrumzan , and thank you very much for the quick response and for looking into the "forward compatibility" feature. That would definitely help mitigate this specific issue with strict enum validation.

To answer your question, we currently don't update the SDK unless it's strictly necessary (e.g., we need a new feature). We operated under the assumption that the underlying REST API was versioned, and that any breaking changes would go through a standard deprecation cycle and a grace period before affecting existing consumers.

Based on what you mentioned about the SDK being regenerated 24-48 hours after the API changes go live, it seems currently impossible for us to anticipate these breakages and adapt our code in time.

This leads me to a couple of follow-up questions:

Is there any platform, roadmap, or changelog where we can see these API changes before they occur in production?

Are there any plans in the future to introduce API versioning and deprecation cycles so that older SDKs aren't abruptly broken by upstream changes?

Thank you again for your time and help!

[RodrigoTomeES]

Hi @ismaelrumzan I accidentally closed the issue 🤦🏼‍♂️ , could you reopen it? please