feat(sdk): add proper error handling (#15148)

Fixes #14495

The SDK now throws a proper `PayloadSDKError` class on failed API
requests instead of either returning undefined or a generic `Error`.
Error handling is centralized in the `request()` method, which adds
error handling for operations where it was previously missing (like
`create`, `update`, `delete`, `find`, etc.).

**Changes:**
- Added `PayloadSDKError` class with `status`, `errors`, `response`, and
`message` properties
- Centralized error handling in `request()` - all operations now
properly throw on failed responses. Previously, some operations (like
`findByID`) just threw a generic Error that did not explain what
actually went wrong and some operations (like `create`) did not throw an
error at all and simply returned undefined.
- Lots of new int tests

**Usage:**
```ts
import { PayloadSDKError } from '@payloadcms/sdk'

try {
  await sdk.create({ collection: 'posts', data: { ... } })
} catch (err) {
  if (err instanceof PayloadSDKError) {
    console.log(err.status)  // 400
    console.log(err.errors)  // [{ name: 'ValidationError', message: '...', data: {...} }]
  }
}
```

Author: AlessioGr

packages/payload/src/config/types.ts

@@ -699,7 +699,16 @@ export type FetchAPIFileUploadOptions = {
   useTempFiles?: boolean | undefined
 } & Partial<BusboyConfig>
 
-export type ErrorResult = { data?: any; errors: unknown[]; stack?: string }
+export type ErrorResult = {
+  data?: any
+  errors: {
+    data?: Record<string, unknown>
+    field?: string
+    message?: string
+    name?: string
+  }[]
+  stack?: string
+}
 
 export type AfterErrorResult = {
   graphqlResult?: GraphQLFormattedError

packages/payload/src/utilities/formatErrors.ts

@@ -18,9 +18,9 @@ export const formatErrors = (incoming: { [key: string]: unknown } | APIError): E
       return {
         errors: [
           {
-            name: incoming.name,
-            data: incoming.data,
-            message: incoming.message,
+            name: incoming.name as string,
+            data: incoming.data as Record<string, unknown>,
+            message: incoming.message as string,
           },
         ],
       }
@@ -52,7 +52,7 @@ export const formatErrors = (incoming: { [key: string]: unknown } | APIError): E
       return {
         errors: [
           {
-            message: incoming.message,
+            message: incoming.message as string,
           },
         ],
       }

packages/sdk/src/collections/findByID.ts

@@ -78,17 +78,13 @@ export async function findByID<
       path: `/${options.collection}/${options.id}`,
     })
 
-    if (response.ok) {
-      return response.json()
-    } else {
-      throw new Error()
-    }
-  } catch {
+    return response.json()
+  } catch (err) {
     if (options.disableErrors) {
       // @ts-expect-error generic nullable
       return null
     }
 
-    throw new Error(`Error retrieving the document ${options.collection}/${options.id}`)
+    throw err
   }
 }

packages/sdk/src/collections/findVersionByID.ts

@@ -79,17 +79,13 @@ export async function findVersionByID<
       path: `/${options.collection}/versions/${options.id}`,
     })
 
-    if (response.ok) {
-      return response.json()
-    } else {
-      throw new Error()
-    }
-  } catch {
+    return response.json()
+  } catch (err) {
     if (options.disableErrors) {
       // @ts-expect-error generic nullable
       return null
     }
 
-    throw new Error(`Error retrieving the version document ${options.collection}/${options.id}`)
+    throw err
   }
 }

packages/sdk/src/errors/PayloadSDKError.ts

@@ -0,0 +1,37 @@
+import type { ErrorResult } from 'payload'
+
+/**
+ * Error class for SDK API errors.
+ * Contains the HTTP status code and error details from the API response.
+ */
+export class PayloadSDKError extends Error {
+  /**
+   * The error data from the API response.
+   * For ValidationError, this contains `collection`, `global`, and `errors` array.
+   */
+  errors: ErrorResult['errors']
+
+  /** The response object */
+  response: Response
+
+  /** HTTP status code */
+  status: number
+
+  constructor({
+    errors,
+    message,
+    response,
+    status,
+  }: {
+    errors: ErrorResult['errors']
+    message: string
+    response: Response
+    status: number
+  }) {
+    super(message)
+    this.name = 'PayloadSDKError'
+    this.status = status
+    this.errors = errors
+    this.response = response
+  }
+}

packages/sdk/src/globals/findVersionByID.ts

@@ -67,17 +67,13 @@ export async function findGlobalVersionByID<
       path: `/globals/${options.slug}/versions/${options.id}`,
     })
 
-    if (response.ok) {
-      return response.json()
-    } else {
-      throw new Error()
-    }
-  } catch {
+    return response.json()
+  } catch (err) {
     if (options.disableErrors) {
       // @ts-expect-error generic nullable
       return null
     }
 
-    throw new Error(`Error retrieving the version document ${options.slug}/${options.id}`)
+    throw err
   }
 }

packages/sdk/src/index.ts

@@ -1,4 +1,12 @@
-import type { ApplyDisableErrors, PaginatedDocs, SelectType, TypeWithVersion } from 'payload'
+import type {
+  ApplyDisableErrors,
+  ErrorResult,
+  PaginatedDocs,
+  SelectType,
+  TypeWithVersion,
+} from 'payload'
+
+export { PayloadSDKError } from './errors/PayloadSDKError.js'
 
 import type { ForgotPasswordOptions } from './auth/forgotPassword.js'
 import type { LoginOptions, LoginResult } from './auth/login.js'
@@ -51,6 +59,7 @@ import {
   type UpdateManyOptions,
   type UpdateOptions,
 } from './collections/update.js'
+import { PayloadSDKError } from './errors/PayloadSDKError.js'
 import { findGlobal, type FindGlobalOptions } from './globals/findOne.js'
 import { findGlobalVersionByID } from './globals/findVersionByID.js'
 import { findGlobalVersions } from './globals/findVersions.js'
@@ -310,6 +319,31 @@ export class PayloadSDK<T extends PayloadGeneratedTypes = PayloadGeneratedTypes>
 
     const response = await this.fetch(`${this.baseURL}${path}${buildSearchParams(args)}`, init)
 
+    if (!response.ok) {
+      let errorData: {
+        message?: string
+      } & Partial<ErrorResult> = {}
+
+      try {
+        errorData = await response.json()
+      } catch {
+        // Response body may not be JSON
+      }
+
+      const errors: ErrorResult['errors'] = errorData.errors ?? [
+        { message: errorData.message ?? response.statusText },
+      ]
+
+      const message = errors[0]?.message ?? response.statusText
+
+      throw new PayloadSDKError({
+        errors,
+        message,
+        response,
+        status: response.status,
+      })
+    }
+
     return response
   }
 

test/sdk/collections/Emails.ts

@@ -0,0 +1,20 @@
+import type { CollectionConfig } from 'payload'
+
+export const emailsSlug = 'emails'
+
+export const EmailsCollection: CollectionConfig = {
+  slug: emailsSlug,
+  access: { create: () => true, update: () => true, delete: () => true, read: () => true },
+  fields: [
+    {
+      name: 'email',
+      type: 'email',
+      unique: true,
+      required: true,
+    },
+    {
+      name: 'name',
+      type: 'text',
+    },
+  ],
+}

test/sdk/config.ts

@@ -5,6 +5,7 @@ const dirname = path.dirname(filename)
 
 import { buildConfigWithDefaults } from '../buildConfigWithDefaults.js'
 import { devUser } from '../credentials.js'
+import { EmailsCollection } from './collections/Emails.js'
 import { PostsCollection } from './collections/Posts.js'
 import { Users } from './collections/Users.js'
 
@@ -17,6 +18,7 @@ export default buildConfigWithDefaults({
   collections: [
     Users,
     PostsCollection,
+    EmailsCollection,
     {
       access: { create: () => true, read: () => true, update: () => true },
       slug: 'media',