SDK Error Reference
This reference documents all error codes returned by the Fanfare SDK, their meanings, and recommended resolutions.Error Structure
All SDK errors follow a consistent structure:Handling Errors
Network Errors
NETWORK_ERROR
Description: Request failed due to network connectivity issues. Common Causes:- No internet connection
- DNS resolution failure
- Network timeout
- Server unreachable
TIMEOUT
Description: Request timed out waiting for a response. Common Causes:- Slow network connection
- Server under heavy load
- Request too large
ABORTED
Description: Request was cancelled before completion. Common Causes:- User navigated away from page
- Component unmounted
- Explicit cancellation
Authentication Errors
UNAUTHORIZED
Description: Request requires authentication. HTTP Status: 401 Common Causes:- No session active
- Session was cleared
- Invalid credentials
SESSION_EXPIRED
Description: Authentication session has expired. HTTP Status: 401 Common Causes:- Session timeout
- Server-side session invalidation
- Token expiration
INVALID_CREDENTIALS
Description: Provided credentials are incorrect. HTTP Status: 401 Common Causes:- Wrong email/password combination
- Account doesn’t exist
- Account locked
INVALID_OTP
Description: One-time password verification failed. HTTP Status: 401 Common Causes:- Incorrect code entered
- Code has expired
- Code already used
Queue Errors
QUEUE_NOT_FOUND
Description: The specified queue does not exist. Common Causes:- Invalid queue ID
- Queue has been deleted
- Queue not yet created
QUEUE_EXPIRED
Description: The queue has ended and is no longer accepting entries. Common Causes:- Queue end time has passed
- Queue was manually closed
- All inventory distributed
QUEUE_FULL
Description: The queue has reached maximum capacity. Common Causes:- Queue participant limit reached
- High demand exceeded capacity
ALREADY_IN_QUEUE
Description: User is already in this queue. Common Causes:- Duplicate entry attempt
- Re-entry after page refresh
NOT_IN_QUEUE
Description: User is not in the specified queue. Common Causes:- Never entered the queue
- Left the queue previously
- Session mismatch
Validation Errors
VALIDATION_ERROR
Description: Request data failed validation. HTTP Status: 400 or 422 Common Causes:- Missing required fields
- Invalid field values
- Data format issues
INVALID_PARAMETERS
Description: Request parameters are invalid. HTTP Status: 400 Common Causes:- Invalid ID format
- Out-of-range values
- Unsupported parameters
Rate Limiting
RATE_LIMITED
Description: Too many requests in a short period. HTTP Status: 429 Headers:X-RateLimit-Limit: Maximum requests allowedX-RateLimit-Remaining: Requests remainingRetry-After: Seconds to wait before retrying
Server Errors
INTERNAL_ERROR
Description: An unexpected server error occurred. HTTP Status: 500 Resolution:SERVICE_UNAVAILABLE
Description: The service is temporarily unavailable. HTTP Status: 503 Common Causes:- Maintenance window
- Capacity issues
- Deployment in progress
SDK Configuration Errors
NOT_INITIALIZED
Description: SDK operation called before initialization. Common Causes:- Calling methods before creating client
- Client creation failed
- Async initialization not awaited
ALREADY_INITIALIZED
Description: Attempted to initialize SDK when already initialized. Resolution: Use a single client instance throughout your application. Retryable: NoINVALID_CONFIG
Description: SDK configuration is invalid. Common Causes:- Missing required configuration
- Invalid configuration values
- Incompatible options
Fingerprint Errors
FP001 - FINGERPRINT_REQUIRED
Description: Device fingerprint is required but not provided. HTTP Status: 400 Resolution: Ensure the SDK is properly initialized with fingerprinting enabled.FP002 - DEVICE_MISMATCH
Description: Current device fingerprint doesn’t match the original device. HTTP Status: 403 Common Causes:- Accessing from different device
- Browser profile changed
- Significant browser configuration changes
FP003 - FINGERPRINT_INVALID
Description: Fingerprint format is invalid. HTTP Status: 400 Common Causes:- SDK version mismatch
- Browser fingerprinting blocked
- Corrupted fingerprint data
Best Practices
Error Logging
Log errors with context for debugging.User-Friendly Messages
Map technical errors to user-friendly messages.Related Resources
- API Errors - HTTP API error reference
- Common Issues - Troubleshooting guide
- Contact Support - Get help