Skip to content

error-handling.md

Latest commit

 

History

History
124 lines (86 loc) · 4.46 KB

error-handling.md

File metadata and controls

124 lines (86 loc) · 4.46 KB
Raw
title Error handling
description Unified error shape returned by all SDK form hooks and error handlers. Every caught error — API, validation, network, or runtime — is normalized into `SDKError`.
sidebar_position 11
generated_by typedoc
custom_edit_url

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

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)