API Reference

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.

Download README

Error Response Format

When an error occurs, the Lumyx AI API returns a structured JSON response with details about the error:

Error Response Structure
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

200 OK Request successful

The request was successful and the response contains the requested data.

201 Created Resource created

A new resource was successfully created (e.g., new conversation).

Client Error Codes

400 Bad Request Invalid request

The request was malformed or contains invalid parameters.

402 Payment Required Insufficient balance

Your account balance is insufficient to process the request. Please top up your account.

401 Unauthorized Authentication failed

Invalid or missing API key, or the key lacks necessary permissions.

403 Forbidden Access denied

The API key is valid but doesn't have permission to access the requested resource.

404 Not Found Resource not found

The requested resource (conversation, persona, etc.) doesn't exist.

422 Unprocessable Validation error

The request format is correct but contains invalid data that failed validation.

429 Too Many Requests Rate limit exceeded

You've exceeded your rate limit. Check rate limit headers for retry timing.

Server Error Codes

500 Internal Server Error Server error

An unexpected error occurred on our servers. These should be rare.

502 Bad Gateway Upstream error

Error communicating with the AI model backend. Usually temporary.

503 Service Unavailable Service unavailable

The service is temporarily unavailable, often due to maintenance.

504 Gateway Timeout Timeout

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.

HTTP Status: 400, 422

authentication_error

Authentication failed due to invalid, missing, or expired API keys.

HTTP Status: 401

permission_error

The API key is valid but lacks permission to perform the requested action.

HTTP Status: 403

rate_limit_exceeded

Too many requests have been made in the current time window.

HTTP Status: 429

insufficient_quota

Your account does not have enough credits to perform this action.

HTTP Status: 402

resource_not_found

The requested resource (conversation, persona, etc.) doesn't exist.

HTTP Status: 404

server_error

An unexpected error occurred on Lumyx AI's servers.

HTTP Status: 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

JavaScript
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