feat(storage): expose the service error code on StorageException

[spydon]

Closes #1650. SDK-1426.

Stacked on #1647, which is where StorageException becomes a SupabaseException and its fromJson gets its defensive field reads. Review that one first; the diff here is only the last commit.

Storage answers a failed request with a body like:

{ "statusCode": "404", "error": "not_found", "code": "NoSuchKey", "message": "Object not found" }

code is the documented storage error code and is what STORAGE-629 added to the server's error schema. supabase-js picked it up in supabase/supabase-js#2537 as a new code field on StorageApiError.

The Dart shape

A second code field alongside errorCode would give storage two overlapping identifiers and undo the point of the unified exception in this stack, so code goes into SupabaseException.errorCode instead. That field is already documented as "service specific identifier for the error", which is exactly what this is.

error stays as the fallback for servers that predate the schema change. It is not a good primary source: against a local stack, the same field is not_found for a missing object and Bucket not found for a missing bucket, so it carries a plain sentence about as often as an identifier. code does not have that problem.

try {
  await supabase.storage.from('avatars').download('missing.png');
} on StorageException catch (error) {
  if (error.errorCode == 'NoSuchKey') {
    // ...
  }
}

The example in SupabaseException.errorCode's doc comment moves from not_found to NoSuchKey to match what storage now yields.

Testing

types_test.dart covers the three fromJson branches (code wins over error, error as fallback, null when the body has neither). basic_test.dart covers the same through a real request, so the value survives the fetch layer rather than only the factory.

melos analyze and melos format clean. The full storage_client suite passes against a local stack (220 tests), as does supabase_common.

Compliance matrix

storage.errors.error_codes → implemented. Symbol, drift and schema checks pass locally.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: dc75a1f3-bf9c-471b-a743-a0cad6eae3c1

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}