Error Handling
Error handling guide
Error Handling
The SDK throws errors and provides type-safe error classes and type guards.
Error Types
| Error Class | Code | Description |
|---|---|---|
NetworkError | NETWORK_ERROR | Network connection failure |
ApiError | API_ERROR | HTTP error (includes status code) |
ValidationError | VALIDATION_ERROR | Data validation failure (400) |
TimeoutError | TIMEOUT_ERROR | Request timeout (408) |
UsageLimitError | USAGE_LIMIT_ERROR | Monthly API quota exceeded (429) |
GoneError | GONE_ERROR | Resource gone (410) |
ServiceUnavailableError | SERVICE_UNAVAILABLE_ERROR | Service unavailable (503, includes retryAfter) |
ConfigError | CONFIG_ERROR | Configuration error |
All errors extend SDKError and provide getUserMessage() and a suggestion property.
Type Guards
import {
isNetworkError,
isApiError,
isValidationError,
isTimeoutError,
isUsageLimitError,
isGoneError,
isServiceUnavailableError,
} from '@01.software/sdk'
try {
const { docs } = await client.from('products').find()
} catch (error) {
if (isNetworkError(error)) {
// Network error
} else if (isApiError(error)) {
// API error (error.statusCode available)
} else if (isValidationError(error)) {
// Validation error
} else if (isTimeoutError(error)) {
// Timeout
} else if (isUsageLimitError(error)) {
// Monthly API quota exceeded (check usage via error.usage)
} else if (isGoneError(error)) {
// Resource gone (410)
} else if (isServiceUnavailableError(error)) {
// Service unavailable (check error.retryAfter for retry timing)
}
}React Query Error Handling
const { data, error, isError } = client.query.useQuery({
collection: 'products',
options: { limit: 10 },
})
if (isError) {
return <div>{error.getUserMessage()}</div>
}Retry Behavior
The SDK automatically retries requests internally.
- Default max retries: 3
- Retryable statuses: 408, 429, 500, 502, 503, 504
- Non-retryable: 401, 403, 404, 422 (always fail immediately)
- Delay:
Math.min(1000 * 2^attempt, 10000)(1s → 2s → 4s)
Monthly API quota exceeded (429 + X-Usage-Limit header) is not retried and throws UsageLimitError immediately.