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: Swift 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-swift's Sources/Auth/Internal/APIClient.swift handleError returns a hardcoded message: "Unexpected error" when the body isn't decodable as _RawAPIErrorResponse per prior investigation — it doesn't preserve the actual HTTP status text/reason phrase. Fall back to the response's status description when the body can't be decoded, and only use a generic message as a last resort.

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 Swift 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:

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

[mmarufov]

Hi! I confirmed that APIClient.handleError still returns the generic "Unexpected error" when _RawAPIErrorResponse decoding fails. I'd like to implement the status-aware fallback described here and add regression tests for a non-JSON 5xx response plus the empty-body fallback. I'll preserve existing JSON error handling and avoid public API changes.

One note from investigating: HTTPURLResponse doesn't expose the reason phrase on any platform, so the closest analog is HTTPURLResponse.localizedString(forStatusCode:) (already used by RealtimeChannelV2 for the same purpose). Since that description is localized on Darwin and differs from the Linux one, I'm planning to always include the status code, e.g. HTTP 503: service unavailable. Happy to adjust the shape if you prefer the bare description.