Error Handling
Learn how to handle errors gracefully when working with the Lumyx AI API. Understand error codes, response formats, and best practices for error handling.
Error Response Format
When an error occurs, the Lumyx AI API returns a structured JSON response with details about the error:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": {
"message": "The model 'invalid-model' does not exist.",
"type": "invalid_request_error",
"param": "model",
"code": "model_not_found"
}
}
Error Object Fields
message
string
A human-readable description of the error suitable for displaying to users.
type
string
The type of error that occurred. Used for programmatic error handling.
param
string or null
The parameter that caused the error, if applicable. Helpful for validation errors.
code
string
A specific error code for programmatic handling. More granular than the error type.
HTTP Status Codes
The Lumyx AI API uses standard HTTP status codes to indicate the success or failure of requests:
Success Codes
The request was successful and the response contains the requested data.
A new resource was successfully created (e.g., new conversation).
Client Error Codes
The request was malformed or contains invalid parameters.
Your account balance is insufficient to process the request. Please top up your account.
Invalid or missing API key, or the key lacks necessary permissions.
The API key is valid but doesn't have permission to access the requested resource.
The requested resource (conversation, persona, etc.) doesn't exist.
The request format is correct but contains invalid data that failed validation.
You've exceeded your rate limit. Check rate limit headers for retry timing.
Server Error Codes
An unexpected error occurred on our servers. These should be rare.
Error communicating with the AI model backend. Usually temporary.
The service is temporarily unavailable, often due to maintenance.
The request took too long to process. The AI model may be overloaded.
Error Types
The type field helps you categorize errors for appropriate handling:
invalid_request_error
The request is malformed, missing required parameters, or contains invalid values.
400, 422
authentication_error
Authentication failed due to invalid, missing, or expired API keys.
401
permission_error
The API key is valid but lacks permission to perform the requested action.
403
rate_limit_exceeded
Too many requests have been made in the current time window.
429
insufficient_quota
Your account does not have enough credits to perform this action.
402
resource_not_found
The requested resource (conversation, persona, etc.) doesn't exist.
404
server_error
An unexpected error occurred on Lumyx AI's servers.
500, 502, 503
Common Error Codes
Specific error codes for common scenarios:
| Error Code | Description | How to Fix |
|---|---|---|
invalid_api_key |
The provided API key is invalid or malformed | Check your API key format and ensure it starts with "nova_" |
missing_api_key |
No API key was provided in the request | Include the Authorization header with your API key |
expired_api_key |
The API key has expired | Create a new API key or extend the current one's expiration |
model_not_found |
The specified model doesn't exist | Use a valid model ID (e.g., nova_1_1) |
persona_not_found |
The specified persona doesn't exist | Check the persona ID or list available personas |
conversation_not_found |
The conversation ID doesn't exist | Verify the conversation UUID or start a new conversation |
invalid_messages_format |
The messages array format is incorrect | Ensure each message has "role" and "content" fields |
content_too_long |
The input content exceeds the model's context limit | Reduce message length or use a model with larger context |
rate_limit_exceeded |
Too many requests in the current time window | Wait and retry, or implement exponential backoff |
insufficient_balance |
Account balance is too low | Top up your account in the billing dashboard |
uncensored_policy_required |
Uncensored Model Usage Policy not accepted | Accept policy in Developer Dashboard > Legal |
detailed_logging_required |
Detailed logging is required/disabled | Enable detailed logging for your API key |
Error Handling Examples
JavaScript Error Handling
async function handleAPICall() {
try {
const response = await fetch('https://api.lumyx-ai.site/v1/chat/completions', {
method: 'POST',
headers: {
'Authorization': 'Bearer nova_your_api_key_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({
model: 'nova_1_1',
messages: [{ role: 'user', content: 'Hello!' }]
})
});
if (!response.ok) {
const errorData = await response.json();
const error = errorData.error;
switch (error.type) {
case 'authentication_error':
throw new Error('API key is invalid or missing');
case 'rate_limit_exceeded':
const retryAfter = response.headers.get('Retry-After');
throw new Error(`Rate limited. Retry after ${retryAfter} seconds`);
case 'insufficient_quota':
throw new Error('Insufficient funds. Please top up your account.');
case 'invalid_request_error':
throw new Error(`Invalid request: ${error.message}`);
default:
throw new Error(`API error: ${error.message}`);
}
}
return await response.json();
} catch (error) {
console.error('Error:', error.message);
throw error;
}
}
Best Practices
Handle Errors Gracefully
- Always check HTTP status codes
- Parse error responses for details
- Provide user-friendly error messages
- Log errors for debugging
Implement Retry Logic
- Retry on 5xx and 429 errors
- Use exponential backoff
- Respect Retry-After headers
- Set maximum retry limits
Validate Input
- Check required parameters
- Validate message format
- Check content length limits
- Sanitize user input
Monitor and Alert
- Track error rates
- Monitor API key usage
- Set up rate limit alerts
- Use analytics dashboard