JA EN
shiichan

Cloudflare TypeScript SDK v6.0.0: Retry-After Handling Gets a Surprise Overhaul!

Cloudflare Changelog ★★★★ View Markdown
#cloudflare#devops#infrastructure

Hi, it's me! Today I found a slightly heavier piece of news from Cloudflare's developer world that I wanted to share. It looks understated, but there's a lot packed into it.

Cloudflare Changelog developers.cloudflare.com

What was announced?

Cloudflare's Changelog announced the release of major version v6.0.0 of the official TypeScript SDK. It's a major upgrade from the v5.x line, adding 11 entirely new top-level API resources, new sub-resources and methods across more than 50 existing resources, and several breaking changes to the SDK's internal behavior.

The story so far

The v5.x line of the SDK had a few quietly annoying behaviors.

  • When a request got rate-limited, if the server-specified Retry-After value was over 60 seconds, the SDK ignored it and used its own default backoff instead
  • For empty responses with content-length: 0, the SDK still dutifully tried to parse the body
  • Empty-string environment variables (like CLOUDFLARE_API_TOKEN="") were treated as if a value had been set

They all sound minor on their own, but in practice they caused real pain: retry timing after rate limits got thrown off, parsing empty bodies produced unexpected errors, and blank auth tokens could get sent as-is.

What changes

v6.0.0 fixes all of this in one go.

  • The SDK now respects the server-specified Retry-After value even when it's over 60 seconds, making recovery from rate limits more accurate
  • Responses with content-length: 0 now return undefined instead of attempting to parse the body
  • Empty-string environment variables are now treated as unset, preventing the SDK from accidentally sending an empty token as credentials

On top of that, 11 entirely new top-level resources — including AI Search, Realtime Kit, and Organizations — are now fully available, opening up functionality that wasn't reachable through the SDK before. That said, upgrading from v5.x also brings 17 removed HTTP endpoints and method signature changes, so a straight swap could break your build if you're not careful.

Dive Deep

Here are the 11 newly added top-level resources.

  • client.realtimeKit — Realtime Kit API, 54 methods
  • client.aiSearch — AI Search instances, namespaces, and token management, 46 methods
  • client.vulnerabilityScanner — vulnerability scanning, 21 methods
  • client.tokenValidation — token validation rules, 13 methods
  • client.r2DataCatalog — R2 Data Catalog, 11 methods
  • client.resourceTagging — resource tagging, 9 methods
  • client.organizations — organization profiles, audit logs, and more, 8 methods
  • client.emailSending — email sending endpoints, 7 methods
  • client.connectivity — directory services API, 5 methods
  • client.googleTagGateway — Google Tag Gateway management, 2 methods
  • client.fraud — fraud detection API, 2 methods

The 17 removed HTTP endpoints affect resources including abuse-reports, cloudforce-one, dlp/profiles/predefined, email-security/investigate, email-security/settings, and intel/ip-list, so any code touching those should be checked before migrating.

Some method signatures changed too — for example, argument passing shifted like this:

// v5.x
client.ai.toMarkdown.transform(file, { ...params });

// v6.0.0
client.ai.toMarkdown.transform({ ...params });

There are also path renames: client.originTLSClientAuth.hostnames.certificates becomes client.originTLSClientAuth.zoneCertificates, and client.radar.netflows becomes client.radar.netFlows. On top of that, there are 179 return-type changes (133 methods shifting toward null-centric types for delete-style operations, 17 pagination type changes, and 29 renamed types), plus 43 types removed or merged.

Wrap-up

  • Cloudflare's TypeScript SDK got a major update to v6.0.0
  • Retry-After is now respected even above 60 seconds, empty responses return undefined, and empty-string env vars are treated as unset
  • 17 HTTP endpoints were removed, affecting abuse-reports, email-security, and more
  • 11 new top-level resources were added, including AI Search, Realtime Kit, and Organizations
  • Method signatures and path names changed in places, alongside 179 return-type changes

If you're calling Cloudflare's API from TypeScript or JavaScript, it's worth comparing the breaking-change list before upgrading — especially if your code has its own workarounds for the old Retry-After behavior.

Related posts