The { data, error }
Pattern
All SDK methods return a consistent object with data
and error
properties, allowing for easy, type-safe error handling.
Type-Safe Error Handling
Error Types & Codes
The SDK provides structured error responses with consistent codes:Authentication Errors
Authentication Errors
Automatically handled by SDK, but you can detect them:Common Codes:
UNAUTHORIZED
- Invalid or expired tokenTOKEN_EXPIRED
- Token needs refresh (handled automatically)INVALID_CREDENTIALS
- Login failed
Validation Errors
Validation Errors
Field-specific validation failures:Common Codes:
VALIDATION_ERROR
- Field validation failedINVALID_INPUT
- Malformed request dataCONSTRAINT_VIOLATION
- Business rule violation
Resource Errors
Resource Errors
Missing or unavailable resources:Common Codes:
NOT_FOUND
- Resource doesn’t existACCESS_DENIED
- Insufficient permissionsRESOURCE_CONFLICT
- Conflicting operation
Network Errors
Network Errors
Connection and timeout issues:Common Codes:
NETWORK_ERROR
- Connection failedTIMEOUT
- Request timed outUNAUTHORIZED
- Authentication failed
Automatic Error Recovery
Token Refresh
The SDK automatically handles token expiry:Authentication Recovery
The SDK automatically handles token refresh and authentication recovery:Error Handling Patterns
Component Error Boundaries
Form Validation
Global Error Handler
Error Monitoring
Custom Error Logging
Error Analytics
Best Practices
Show User-Friendly Messages
Avoid exposing raw API errors to users.
Log Errors for Debugging
Use a monitoring service to track and analyze errors.
Implement Retries Strategically
Use retries for network errors, not for validation or server errors.
Use Error Boundaries
Prevent UI crashes by wrapping components in error boundaries.
Cross-References
- API Error Codes: See API Reference for detailed error responses
- Authentication Flows: Authentication Guide for login/logout patterns
- SDK Debugging: Debugging & Performance for troubleshooting
The SDK’s error handling builds on top of the patterns described in the Storefront Guides, providing automatic recovery and type safety for a better developer experience.