{"record":{"id":"576a1f671649e3fc","repo":"payloadcms/payload","slug":"message","errorCode":null,"errorMessage":"${message}","messagePattern":"\\$\\{message\\}","errorType":"http","errorClass":"PayloadSDKError","httpStatus":null,"severity":"error","filePath":"packages/sdk/src/index.ts","lineNumber":340,"sourceCode":"\n    if (!response.ok) {\n      let errorData: {\n        message?: string\n      } & Partial<ErrorResult> = {}\n\n      try {\n        errorData = await response.json()\n      } catch {\n        // Response body may not be JSON\n      }\n\n      const errors: ErrorResult['errors'] = errorData.errors ?? [\n        { message: errorData.message ?? response.statusText },\n      ]\n\n      const message = errors[0]?.message ?? response.statusText\n\n      throw new PayloadSDKError({\n        errors,\n        message,\n        response,\n        status: response.status,\n      })\n    }\n\n    return response\n  }\n\n  resetPassword<TSlug extends AuthCollectionSlug<T>>(\n    options: ResetPasswordOptions<T, TSlug>,\n    init?: RequestInit,\n  ): Promise<ResetPasswordResult<T, TSlug>> {\n    return resetPassword(this, options, init)\n  }\n\n  restoreGlobalVersion<TSlug extends GlobalSlug<T>>(","sourceCodeStart":322,"sourceCodeEnd":358,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/sdk/src/index.ts#L322-L358","documentation":"Thrown by the Payload SDK's request helper whenever the underlying `fetch` returns a non-OK status. It parses the response body for `errors`/`message` (falling back to `response.statusText`) and wraps them in a `PayloadSDKError` carrying `status`, `response`, and the structured `errors` array. This is the SDK's universal catch-all — the real cause is whatever the server returned (validation, auth, not-found, server error).","triggerScenarios":"Any SDK call (find, create, update, delete, auth) where the server responds with a non-2xx status — validation error (400), unauthorized (401), forbidden (403), not found (404), or server error (500). The body is JSON with `errors` or `message`, or non-JSON (then `statusText` is used).","commonSituations":"Sending invalid field values that fail server-side validation; expired/missing auth token; querying a non-existent collection or document ID; server threw during a hook; network proxy returning an HTML error page (non-JSON body).","solutions":["Inspect `error.status` to route handling (401 → re-auth, 404 → not-found UX, 400 → show `error.errors`)","Read `error.errors` (the structured array) for field-level validation messages","If `error.message === response.statusText` and the body was non-JSON, a proxy/CDN likely intercepted — check the raw network response","Reproduce the request with the same headers/cookie via curl to see the raw server response"],"exampleFix":"// before — unhandled rejection\nawait sdk.find({ collection: 'posts', where: { id: { equals: 'bad' } } })\n// after — branch on status\ntry {\n  await sdk.find({ collection: 'posts', where: { id: { equals: id } } })\n} catch (e) {\n  if (e instanceof PayloadSDKError) {\n    if (e.status === 401) await relogin()\n    else if (e.status === 400) showErrors(e.errors)\n  }\n  throw e\n}","handlingStrategy":"try-catch","validationCode":"// Pre-validate the call shape against the collection schema where possible\n// (field types, required fields) to avoid the common 400 path before it hits the server","typeGuard":"import { PayloadSDKError } from '@payloadcms/sdk'\n// or: function isPayloadSDKError(e: unknown): e is PayloadSDKError { return e instanceof PayloadSDKError }\nfunction isPayloadSDKError(e: unknown): e is { status: number; errors: { message: string }[]; message: string } {\n  return !!e && typeof (e as any).status === 'number' && Array.isArray((e as any).errors)\n}","tryCatchPattern":"try {\n  await sdk.find({ collection: 'posts', where })\n} catch (e) {\n  if (isPayloadSDKError(e)) {\n    if (e.status === 401) await relogin()\n    else if (e.status === 400) showFieldErrors(e.errors)\n    else if (e.status === 404) showNotFound()\n  }\n  throw e\n}","preventionTips":["Always handle the SDK promise — an unhandled rejection loses the structured `errors` array","Branch on `error.status` rather than parsing `error.message`","For non-JSON bodies (proxy/CDN errors), fall back to `response.statusText` diagnostics","Log `error.errors` verbatim so field-level causes are visible in monitoring"],"tags":["sdk","http","error-handling","validation","authentication"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}