Context
In sdk/sdk.go, validateHealthyPlatformConnection returns ErrPlatformUnreachable in two distinct cases:
- Transport failure (the platform is genuinely unreachable)
- The platform is reachable but reports a non-SERVING status (NOT_SERVING / UNKNOWN)
This conflation makes debugging harder for SDK consumers — case 2 means "the platform is up but not ready" which is a fundamentally different operational signal.
Surfaced in #3412 (gemini-code-assist review).
Proposal
Introduce ErrPlatformNotHealthy and return it from case 2; reserve ErrPlatformUnreachable for transport failures only.
Caveat
This is a behavior change — callers of WithConnectionValidation that branch on the existing error will need to update. Consider a deprecation cycle or doc note.
Acceptance
Context
In
sdk/sdk.go,validateHealthyPlatformConnectionreturnsErrPlatformUnreachablein two distinct cases:This conflation makes debugging harder for SDK consumers — case 2 means "the platform is up but not ready" which is a fundamentally different operational signal.
Surfaced in #3412 (gemini-code-assist review).
Proposal
Introduce
ErrPlatformNotHealthyand return it from case 2; reserveErrPlatformUnreachablefor transport failures only.Caveat
This is a behavior change — callers of
WithConnectionValidationthat branch on the existing error will need to update. Consider a deprecation cycle or doc note.Acceptance
ErrPlatformNotHealthydefined and documentedvalidateHealthyPlatformConnectionreturns it for non-SERVING reachable platforms