parity(storage): expose service error code on storage error type [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: b109ea0f
• PR: fix(storage): expose service error code on StorageApiError supabase-js#2537
• Module: storage
• Type: enhancement

What Changed

StorageApiError only exposed message/status/statusCode — callers had to string-match the message to branch on specific failures. Now the service-specific error code from the response body (e.g. NoSuchKey, AccessDenied, ResourceAlreadyExists — see https://supabase.com/docs/guides/storage/debugging/error-codes) is captured as a distinct code field on the error and included in toJSON().

Code Reference

export class StorageApiError extends StorageError {
  code: string | undefined
  constructor(message: string, status: number, statusCode: string, namespace: ErrorNamespace = 'storage', code?: string) {
    super(message, namespace, status, statusCode)
    this.code = code
  }
}

Implementation Guidance

Expected API Surface

supabase-flutter's StorageException (in types.dart per prior investigation) only has message, error, statusCode — add a distinct code field populated from the response body's error code, alongside the existing fields, so callers can branch on it without string-matching message.

Key Behaviors to Match

code field distinct from message/statusCode · Populated from the storage service's error response body · null/absent when the service doesn't provide one

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:

• kt: parity(storage): expose service error code on storage error type [from supabase-js] supabase-community/supabase-kt#1372
• csharp: parity(storage): expose service error code on storage error type [from supabase-js] supabase-community/supabase-csharp#299