parity(auth): preserve HTTP status text on non-JSON 5xx error responses [from supabase-js]

[grdsdev]

Warning

Auto-generated parity issue — may be a false positive.

This issue was created automatically by /sync-sdk-parity from a heuristic
analysis of recent supabase-js commits. The tooling has limited insight
into language-specific idioms and may have:

• misidentified a JS-only change as cross-language relevant,
• missed an existing implementation in this SDK under a different name,
• or proposed an API shape that doesn't fit this language's conventions.

It is the SDK author's responsibility to validate the need before
implementing. If this change does not apply to this SDK, please close the
issue with a short note explaining why.

---

SDK Parity: Dart implementation needed

A change was made in supabase-js that needs to be implemented in this repository for SDK parity.

Reference Implementation (supabase-js)

• Commit: a6bcd6ae
• PR: fix(auth): preserve 5xx error message supabase-js#2587
• Module: auth
• Type: bug-fix

What Changed

When gotrue-js gets a 5xx response whose body isn't valid JSON, it now falls back to the actual HTTP status text/reason phrase instead of a generic/unhelpful message. This matters especially over HTTP/2, where the reason phrase can legitimately be empty, so there's also a final fallback to a synthesized HTTP <status> string.

Code Reference

if (NETWORK_ERROR_CODES.includes(error.status)) {
  // statusText can be empty — HTTP/2 has no reason phrase
  throw new AuthRetryableFetchError(error.statusText || `HTTP ${error.status}`, error.status)
}

Implementation Guidance

Expected API Surface

supabase-flutter's gotrue/lib/src/fetch.dart _handleError for statusCode >= 500 always sets message: response.body with no fallback per prior investigation — when the body is empty/non-JSON, fall back to the response's reason phrase, and if that's also empty, synthesize HTTP <status>.

Key Behaviors to Match

Non-JSON 5xx body with a status line still yields a descriptive message · Empty status line (HTTP/2) falls back to a synthesized message like HTTP 503 · Existing JSON-body error parsing is unaffected

Acceptance Criteria

• Feature/fix implemented matching supabase-js behavior
• Public API follows Dart naming conventions and idioms
• Unit tests cover happy path and edge cases
• Documentation updated
• No breaking changes to existing API (or clearly documented)

Context

• supabase-js version: v3.0.0-next.29
• Parity tracking: This issue was auto-generated by SDK parity analysis

---

Generated with Claude Code /sync-sdk-parity

[grdsdev]

Related parity issues:

• swift: parity(auth): preserve HTTP status text on non-JSON 5xx error responses [from supabase-js] supabase-swift#1171
• kt: parity(auth): preserve HTTP status text on non-JSON 5xx error responses [from supabase-js] supabase-community/supabase-kt#1374