Error Handling

HTTP Status Codes

The Lovina Chat API uses standard HTTP status codes to indicate success or failure.

Code	Meaning	When
200	Success	Request completed successfully
400	Bad Request	Missing required fields, file too large, or malformed request body
401	Unauthorized	Invalid or missing website_token or authToken
404	Not Found	Conversation or message not found
413	Payload Too Large	Uploaded file exceeds the 10 MB size limit
422	Unprocessable Entity	Validation error (e.g., invalid email format)
429	Too Many Requests	Rate limited -- too many requests in a short period
500	Internal Server Error	Unexpected server-side failure

Error Response Format

Error responses follow a consistent JSON structure:

interface ErrorResponse {
  message?: string;                      // Human-readable error description
  errors?: Record<string, string[]>;     // Field-level validation errors
}

Example: Validation Error (422)

{
  "message": "Validation failed",
  "errors": {
    "email": ["is not a valid email address"],
    "identifier": ["can't be blank"]
  }
}

Example: Authentication Error (401)

{
  "message": "Invalid website token"
}

Example: File Too Large (413)

{
  "message": "File size exceeds the maximum limit of 10 MB"
}

Common Errors

Configuration Errors

Error	Cause	Solution
401 Unauthorized on GET /config	Invalid website_token	Verify the token in your Lovina dashboard
Empty or malformed config response	Backend misconfiguration	Check that the backend is running and the widget inbox is set up

Message Errors

Error	Cause	Solution
400 Bad Request on POST /messages	Missing message.content for text messages	Ensure the content field is a non-empty string
413 Payload Too Large	File exceeds 10 MB	Compress or resize the file before uploading
400 Bad Request for file upload	More than 5 files in a single message	Split files across multiple messages
400 Bad Request for file upload	Unsupported MIME type	Only image/*, audio/*, video/*, application/pdf, and text/* are accepted

Conversation Errors

Error	Cause	Solution
404 Not Found on GET /conversations	No conversation exists for this contact	Create a conversation first via POST /conversations
401 Unauthorized on conversation endpoints	Expired or invalid authToken	Re-fetch the config to obtain a new authToken

Rate Limiting

When the API returns 429 Too Many Requests, the client should back off and retry after a delay. The SDK handles this internally with exponential backoff.

SDK-Level Error Events

In addition to HTTP errors, the SDK emits error events through the event callback system for issues such as:

• parse_error -- Failed to parse a message from the WebView bridge
• network_error -- Device lost network connectivity
• auth_failed -- Authentication failed during widget initialization

Handle these in your event listener:

// React Native
onEvent={(event) => {
  if (event.type === 'error') {
    console.error(`[${event.code}]: ${event.message}`);
  }
}}

// Android
is ChatEvent.Error -> {
    Log.e("Chat", "Error [${event.code}]: ${event.message}")
}

// iOS
case .error(let code, let message):
    print("Error [\(code)]: \(message)")

// Flutter
onError: (event) {
    debugPrint('Error [${event.code}]: ${event.message}');
}

CORS

If you are self-hosting the backend, ensure CORS headers are configured:

Access-Control-Allow-Origin: * (or your specific widget domain)
Access-Control-Allow-Methods: GET, POST, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

Missing CORS headers will cause network errors in the WebView on all platforms.