Error handling

Unified error shape returned by all SDK form hooks and error handlers. Every caught error — API, validation, network, or runtime — is normalized into SDKError.

SDKError

Unified error shape returned by every form hook and error-handling surface.

Remarks

Every caught error — whether from the Gusto API, client-side Zod validation, a network failure, or an unexpected runtime exception — is normalized into this shape. The SDKErrorCategory category field distinguishes which source produced the error; fieldErrors is populated for structured API responses (typically 422) and is an empty array otherwise.

Observability telemetry uses ObservabilityError, which extends this shape with component context.

Example

import { useEmployeeForm } from '@gusto/embedded-react-sdk'

const { errorHandling } = useEmployeeForm({ employeeId })
const error = errorHandling.error

if (error) {
  console.log(error.category)    // 'api_error'
  console.log(error.httpStatus)  // 422
  console.log(error.fieldErrors) // [{ field: 'firstName', ... }]
}

Extended by

• ObservabilityError

Properties

Property	Type	Description
category	SDKErrorCategory	High-level error classification
fieldErrors	SDKFieldError[]	Flattened field-level errors from API responses. Empty array for non-field errors.
message	string	Human-readable error summary
httpStatus?	number	HTTP status code (undefined for non-HTTP errors like network or validation)
raw?	unknown	The original error object for advanced use cases. May be stripped by sanitization (controlled by sanitization.includeRawError).

---

SDKErrorCategories

const SDKErrorCategories: object

Constant map of SDKErrorCategory string values keyed by uppercase name.

Remarks

Use this when you need to reference a category value by name (e.g. SDKErrorCategories.API_ERROR). Each entry corresponds to one classification:

Value	When it applies
api_error	HTTP error response from the Gusto API (422, 404, 409, 500, etc.)
validation_error	Client-side Zod schema validation before the request was sent
network_error	Network connectivity failure (connection refused, timeout, abort)
internal_error	Unexpected runtime error (unhandled exception, initialization failure)

Type Declaration

Name	Type
API_ERROR	"api_error"
INTERNAL_ERROR	"internal_error"
NETWORK_ERROR	"network_error"
VALIDATION_ERROR	"validation_error"

---

SDKErrorCategory

SDKErrorCategory = "api_error" | "validation_error" | "network_error" | "internal_error"

High-level classification of where an SDKError originated.

---

SDKFieldError

A flattened, field-level error extracted from an API response.

Remarks

For API errors with structured field errors (e.g. 422 responses), nested errors[] structures are recursively flattened into one entry per leaf field. The field property is the dot-separated camelCase path (e.g. "firstName", "states.CA.filingStatus.value").

Properties

Property	Type	Description
category	string	API error category (e.g. "invalid_attribute_value", "invalid_operation", "payroll_blocker")
field	string	Dot-separated camelCase field path (e.g. "firstName", "states.CA.filingStatus.value")
message	string	Human-readable error message from the API
metadata?	Record<string, unknown>	Additional metadata from the API (e.g. { key: "missing_bank_info" } for payroll blockers)