refactor(client): unify ObjectError across all transports

Rearchitect ObjectError to be transport-agnostic, satisfying all five
principles from the PR #988 review:

1. Consistent errors: same ObjectError class for JSON-RPC, GraphQL, gRPC
2. No transport knowledge needed: error.code works everywhere
3. instanceof works: single class in client/ layer
4. Not coupled to RPC: no transport imports in client/errors.ts
5. Extra info accessible: raw wire payload exposed via error.transportDetails

- ObjectErrorCode is the transport-agnostic union 'notFound' | 'unknown' —
  the only distinctions every transport can reliably produce. JSON-RPC's
  five ObjectResponseError wire codes are normalized on the way in:
  notExists / deleted / dynamicFieldNotFound all surface as 'notFound';
  displayError / unknown surface as 'unknown'. The raw wire payload
  remains available on error.transportDetails for consumers that need it.
- Keep objectId non-nullable: when no id is derivable from a JSON-RPC
  response (e.g. a displayError on listOwnedObjects), escalate to the
  base SuiClientError instead of fabricating a sentinel
- Add TransportDetails, a tagged union ({ \$kind: 'jsonRpc' | 'grpc' |
  'graphql' }) lifted to SuiClientError so every subclass inherits the
  transport escape hatch. ObjectError narrows transportDetails from
  optional to required via 'declare readonly', since every construction
  site passes it
- Narrow GetObjectsResponse.objects from (Object | Error)[] to
  (Object | ObjectError)[] and update 'instanceof Error' checks in the
  composed getObject / getDynamicField / core-resolver paths to the
  tighter 'instanceof ObjectError'. The gRPC unexpected-oneof case
  throws SuiClientError (programmer error) instead of surfacing it as
  data or as a plain Error
- Fix gRPC returning plain Error instead of ObjectError; map
  google.rpc.Code.NOT_FOUND to 'notFound', everything else to 'unknown'
  (NOT_FOUND is hoisted to a named GRPC_CODE_NOT_FOUND constant)
- Replace monolithic mapObjectError with two exhaustive helpers
  (mapJsonRpcObjectErrorCode + extractObjectIdFromResponseError) that
  fail to typecheck if a new wire code is introduced upstream
- Export TransportDetails from @mysten/sui/client
- Unit tests cover: ObjectErrorCode canonical messages, all three
  transport variants, the SuiClientError escalation path in
  listOwnedObjects, JSON-RPC getObjects error mapping across all five
  wire codes (including reference identity of the raw wire payload in
  transportDetails.response), gRPC status code mapping across notFound
  and unknown branches, and a universal catch(SuiClientError) contract
  test that pins compatibility across every wire code
- E2E tests use testWithAllClients to enforce cross-transport parity
  on both getObjects (returns ObjectError) and getObject (throws it)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: Danny-Devs

.changeset/unified-object-errors.md

@@ -0,0 +1,33 @@
+---
+'@mysten/sui': minor
+---
+
+Unify `ObjectError` across all transports. `ObjectError` now carries a
+transport-agnostic `code: 'notFound' | 'unknown'` and a non-nullable `objectId`,
+and works identically regardless of whether the client is backed by JSON-RPC,
+gRPC, or GraphQL.
+
+JSON-RPC's five `ObjectResponseError` wire codes (`notExists`, `deleted`,
+`dynamicFieldNotFound`, `displayError`, `unknown`) are normalized on the way in:
+`notExists`, `deleted`, and `dynamicFieldNotFound` all surface as `'notFound'`;
+`displayError` and `unknown` surface as `'unknown'`. The raw wire payload is
+still available on `error.transportDetails` for consumers that need the richer
+detail.
+
+Adds `TransportDetails`, a tagged union lifted onto the `SuiClientError` base
+class that exposes the raw per-transport payload (JSON-RPC response, gRPC
+`google.rpc.Status`, or a GraphQL tag) via `error.transportDetails`.
+
+`ObjectError.objectId` is always a real object id. In the rare JSON-RPC case
+where the server returns an error that identifies no specific object (e.g. a
+`displayError` surfaced during `listOwnedObjects`), a base `SuiClientError`
+is thrown instead — consumers who catch `SuiClientError` still catch everything.
+
+Also narrows `GetObjectsResponse.objects` from `(Object | Error)[]` to
+`(Object | ObjectError)[]`. Because `ObjectError extends Error`, existing
+`instanceof Error` checks continue to work unchanged.
+
+Newly exports `SuiClientError` (base class), `ObjectError`, `ObjectErrorCode`,
+and `TransportDetails` from `@mysten/sui/client`. Use `instanceof SuiClientError`
+as the universal catch contract for any error originating from the client; use
+`instanceof ObjectError` and switch on `error.code` when you need per-object detail.

packages/sui/src/client/core-resolver.ts

@@ -11,7 +11,7 @@ import { createCoinReservationRef } from '../utils/coin-reservation.js';
 import type { ClientWithCoreApi } from './core.js';
 import type { CallArg, Command } from '../transactions/data/internal.js';
 import type { SuiClientTypes } from './types.js';
-import { SimulationError } from './errors.js';
+import { ObjectError, SimulationError } from './errors.js';
 import { Inputs } from '../transactions/Inputs.js';
 import { getPureBcsSchema, isTxContext } from '../transactions/serializer.js';
 import type { TransactionDataBuilder } from '../transactions/TransactionData.js';
@@ -294,17 +294,18 @@ async function resolveObjectReferences(
 		}),
 	);
 
-	const invalidObjects = Array.from(responsesById)
-		.filter(([_, obj]) => obj instanceof Error)
-		.map(([_, obj]) => (obj as Error).message);
-
-	if (invalidObjects.length) {
-		throw new Error(`The following input objects are invalid: ${invalidObjects.join(', ')}`);
+	// Rethrow the first ObjectError so `instanceof ObjectError` and `error.code` still narrow.
+	// Multi-invalid aggregation is out of scope; introduce `AggregateObjectError` if needed later.
+	const firstInvalid = Array.from(responsesById.values()).find(
+		(obj): obj is ObjectError => obj instanceof ObjectError,
+	);
+	if (firstInvalid) {
+		throw firstInvalid;
 	}
 
 	const objects = resolved.map((object) => {
-		if (object instanceof Error) {
-			throw new Error(`Failed to fetch object: ${object.message}`);
+		if (object instanceof ObjectError) {
+			throw object;
 		}
 		const owner = object.owner;
 		const initialSharedVersion =

packages/sui/src/client/core.ts

@@ -6,6 +6,7 @@ import type { TransactionPlugin } from '../transactions/index.js';
 import { deriveDynamicFieldID } from '../utils/dynamic-fields.js';
 import { normalizeStructTag, parseStructTag, SUI_ADDRESS_LENGTH } from '../utils/sui-types.js';
 import { BaseClient } from './client.js';
+import { ObjectError } from './errors.js';
 import type { ClientWithExtensions, SuiClientTypes } from './types.js';
 import { MvrClient } from './mvr.js';
 import { bcs } from '../bcs/index.js';
@@ -54,7 +55,7 @@ export abstract class CoreClient extends BaseClient implements SuiClientTypes.Tr
 			signal: options.signal,
 			include: options.include,
 		});
-		if (result instanceof Error) {
+		if (result instanceof ObjectError) {
 			throw result;
 		}
 		return { object: result };
@@ -148,7 +149,7 @@ export abstract class CoreClient extends BaseClient implements SuiClientTypes.Tr
 			},
 		});
 
-		if (fieldObject instanceof Error) {
+		if (fieldObject instanceof ObjectError) {
 			throw fieldObject;
 		}
 

packages/sui/src/client/errors.ts

@@ -1,50 +1,78 @@
 // Copyright (c) Mysten Labs, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-import type { ObjectResponseError } from '../jsonRpc/index.js';
 import type { SuiClientTypes } from './types.js';
 
-export class SuiClientError extends Error {}
+/**
+ * Structured per-transport escape hatch attached to any `SuiClientError`.
+ */
+export type TransportDetails =
+	| {
+			$kind: 'jsonRpc';
+			/** The raw `ObjectResponseError` payload from the JSON-RPC response. */
+			response: unknown;
+	  }
+	| {
+			$kind: 'grpc';
+			/** The `google.rpc.Status` attached to the per-object gRPC result. */
+			status: { code: number; message: string; details: unknown[] };
+	  }
+	| {
+			/** No wire payload — GraphQL omits missing objects rather than emitting structured errors. */
+			$kind: 'graphql';
+	  };
+
+export class SuiClientError extends Error {
+	readonly transportDetails?: TransportDetails;
+
+	constructor(
+		message?: string,
+		options?: { cause?: unknown; transportDetails?: TransportDetails },
+	) {
+		super(message, { cause: options?.cause });
+		this.transportDetails = options?.transportDetails;
+	}
+}
 
 export class SimulationError extends SuiClientError {
-	executionError?: SuiClientTypes.ExecutionError;
+	readonly executionError?: SuiClientTypes.ExecutionError;
 
 	constructor(
 		message: string,
-		options?: { cause?: unknown; executionError?: SuiClientTypes.ExecutionError },
+		options?: {
+			cause?: unknown;
+			executionError?: SuiClientTypes.ExecutionError;
+			transportDetails?: TransportDetails;
+		},
 	) {
-		super(message, { cause: options?.cause });
+		super(message, options);
 		this.executionError = options?.executionError;
 	}
 }
 
+export type ObjectErrorCode = 'notFound' | 'unknown';
+
 export class ObjectError extends SuiClientError {
-	code: string;
+	readonly code: ObjectErrorCode;
+	readonly objectId: string;
+	declare readonly transportDetails: TransportDetails;
 
-	constructor(code: string, message: string) {
-		super(message);
+	constructor(
+		code: ObjectErrorCode,
+		objectId: string,
+		options: { cause?: unknown; transportDetails: TransportDetails },
+	) {
+		super(ObjectError.#formatMessage(code, objectId), options);
 		this.code = code;
+		this.objectId = objectId;
 	}
 
-	static fromResponse(response: ObjectResponseError, objectId?: string): ObjectError {
-		switch (response.code) {
-			case 'notExists':
-				return new ObjectError(response.code, `Object ${response.object_id} does not exist`);
-			case 'dynamicFieldNotFound':
-				return new ObjectError(
-					response.code,
-					`Dynamic field not found for object ${response.parent_object_id}`,
-				);
-			case 'deleted':
-				return new ObjectError(response.code, `Object ${response.object_id} has been deleted`);
-			case 'displayError':
-				return new ObjectError(response.code, `Display error: ${response.error}`);
+	static #formatMessage(code: ObjectErrorCode, objectId: string): string {
+		switch (code) {
+			case 'notFound':
+				return `Object not found: ${objectId}`;
 			case 'unknown':
-			default:
-				return new ObjectError(
-					response.code,
-					`Unknown error while loading object${objectId ? ` ${objectId}` : ''}`,
-				);
+				return `Unknown object error: ${objectId}`;
 		}
 	}
 }

packages/sui/src/client/index.ts

@@ -22,7 +22,13 @@ export {
 	type ClientWithCoreApi,
 };
 
-export { SimulationError } from './errors.js';
+export {
+	SuiClientError,
+	SimulationError,
+	ObjectError,
+	type ObjectErrorCode,
+	type TransportDetails,
+} from './errors.js';
 
 export { ClientCache, type ClientCacheOptions } from './cache.js';
 export { type NamedPackagesOverrides } from './mvr.js';

packages/sui/src/client/types.ts

@@ -10,6 +10,7 @@ import type {
 import type { Signer } from '../cryptography/keypair.js';
 import type { ClientCache } from './cache.js';
 import type { BaseClient } from './client.js';
+import type { ObjectError } from './errors.js';
 
 export type SuiClientRegistration<
 	T extends BaseClient = BaseClient,
@@ -141,7 +142,7 @@ export namespace SuiClientTypes {
 	}
 
 	export interface GetObjectsResponse<out Include extends ObjectInclude = {}> {
-		objects: (Object<Include> | Error)[];
+		objects: (Object<Include> | ObjectError)[];
 	}
 
 	export interface GetObjectResponse<out Include extends ObjectInclude = {}> {

packages/sui/src/graphql/core.ts

@@ -108,12 +108,17 @@ export class GraphQLCoreClient extends CoreClient {
 			);
 			results.push(
 				...batch
-					.map((id) => normalizeSuiAddress(id))
-					.map(
-						(id) =>
-							page.find((obj) => obj?.address === id) ??
-							new ObjectError('notFound', `Object ${id} not found`),
-					)
+					.map((rawId) => {
+						// Normalize for server lookup, but preserve `rawId` on ObjectError so
+						// `error.objectId` matches what the user passed in.
+						const normalized = normalizeSuiAddress(rawId);
+						return (
+							page.find((obj) => obj?.address === normalized) ??
+							new ObjectError('notFound', rawId, {
+								transportDetails: { $kind: 'graphql' },
+							})
+						);
+					})
 					.map((obj) => {
 						if (obj instanceof ObjectError) {
 							return obj;

packages/sui/src/grpc/core.ts

@@ -1,8 +1,14 @@
 // Copyright (c) Mysten Labs, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-import type { CoreClientOptions, SuiClientTypes } from '../client/index.js';
-import { CoreClient, formatMoveAbortMessage, SimulationError } from '../client/index.js';
+import type { CoreClientOptions, ObjectErrorCode, SuiClientTypes } from '../client/index.js';
+import {
+	CoreClient,
+	formatMoveAbortMessage,
+	ObjectError,
+	SimulationError,
+	SuiClientError,
+} from '../client/index.js';
 import type { SuiGrpcClient } from './client.js';
 import type { Owner } from './proto/sui/rpc/v2/owner.js';
 import { Owner_OwnerKind } from './proto/sui/rpc/v2/owner.js';
@@ -46,6 +52,10 @@ import {
 import { Value } from './proto/google/protobuf/struct.js';
 import { SimulateTransactionRequest_TransactionChecks } from './proto/sui/rpc/v2/transaction_execution_service.js';
 
+// google.rpc.Code.NOT_FOUND — the only status we map to ObjectError('notFound');
+// any other code collapses to 'unknown'.
+const GRPC_CODE_NOT_FOUND = 5;
+
 export interface GrpcCoreClientOptions extends CoreClientOptions {
 	client: SuiGrpcClient;
 }
@@ -88,51 +98,59 @@ export class GrpcCoreClient extends CoreClient {
 			});
 
 			results.push(
-				...response.response.objects.map((object): SuiClientTypes.Object<Include> | Error => {
-					if (object.result.oneofKind === 'error') {
-						// TODO: improve error handling
-						return new Error(object.result.error.message);
-					}
-
-					if (object.result.oneofKind !== 'object') {
-						return new Error('Unexpected result type');
-					}
-
-					const bcsContent = object.result.object.contents?.value ?? undefined;
-					const objectBcs = object.result.object.bcs?.value ?? undefined;
-
-					// Package objects have type "package" which is not a struct tag, so don't normalize it
-					const objectType = object.result.object.objectType;
-					const type =
-						objectType && objectType.includes('::')
-							? normalizeStructTag(objectType)
-							: (objectType ?? '');
-
-					const jsonContent = options.include?.json
-						? object.result.object.json
-							? (Value.toJson(object.result.object.json) as Record<string, unknown>)
-							: null
-						: undefined;
-
-					const displayData = mapDisplayProto(
-						options.include?.display,
-						object.result.object.display,
-					);
-
-					return {
-						objectId: object.result.object.objectId!,
-						version: object.result.object.version?.toString()!,
-						digest: object.result.object.digest!,
-						content: bcsContent as SuiClientTypes.Object<Include>['content'],
-						owner: mapOwner(object.result.object.owner)!,
-						type,
-						previousTransaction: (object.result.object.previousTransaction ??
-							undefined) as SuiClientTypes.Object<Include>['previousTransaction'],
-						objectBcs: objectBcs as SuiClientTypes.Object<Include>['objectBcs'],
-						json: jsonContent as SuiClientTypes.Object<Include>['json'],
-						display: displayData as SuiClientTypes.Object<Include>['display'],
-					};
-				}),
+				...response.response.objects.map(
+					(object, idx): SuiClientTypes.Object<Include> | ObjectError => {
+						if (object.result.oneofKind === 'error') {
+							const status = object.result.error;
+							const code: ObjectErrorCode =
+								status.code === GRPC_CODE_NOT_FOUND ? 'notFound' : 'unknown';
+							return new ObjectError(code, batch[idx], {
+								transportDetails: { $kind: 'grpc', status },
+							});
+						}
+
+						if (object.result.oneofKind !== 'object') {
+							throw new SuiClientError(
+								`Unexpected gRPC result kind: "${object.result.oneofKind}" — expected "object" or "error"`,
+							);
+						}
+
+						const bcsContent = object.result.object.contents?.value ?? undefined;
+						const objectBcs = object.result.object.bcs?.value ?? undefined;
+
+						// Package objects have type "package" which is not a struct tag, so don't normalize it
+						const objectType = object.result.object.objectType;
+						const type =
+							objectType && objectType.includes('::')
+								? normalizeStructTag(objectType)
+								: (objectType ?? '');
+
+						const jsonContent = options.include?.json
+							? object.result.object.json
+								? (Value.toJson(object.result.object.json) as Record<string, unknown>)
+								: null
+							: undefined;
+
+						const displayData = mapDisplayProto(
+							options.include?.display,
+							object.result.object.display,
+						);
+
+						return {
+							objectId: object.result.object.objectId!,
+							version: object.result.object.version?.toString()!,
+							digest: object.result.object.digest!,
+							content: bcsContent as SuiClientTypes.Object<Include>['content'],
+							owner: mapOwner(object.result.object.owner)!,
+							type,
+							previousTransaction: (object.result.object.previousTransaction ??
+								undefined) as SuiClientTypes.Object<Include>['previousTransaction'],
+							objectBcs: objectBcs as SuiClientTypes.Object<Include>['objectBcs'],
+							json: jsonContent as SuiClientTypes.Object<Include>['json'],
+							display: displayData as SuiClientTypes.Object<Include>['display'],
+						};
+					},
+				),
 			);
 		}