Skip to main content
The Lumenfall API uses standard HTTP status codes and returns errors in an OpenAI-compatible format.

​
Error response format

All error responses follow this structure: 
{
  "error": {
    "message": "Human-readable error description",
    "type": "error_type",
    "code": "ERROR_CODE"
  }
}
FieldDescription
messageA human-readable description of the error
typeThe category of error (e.g., authentication_error, invalid_request_error)
codeA machine-readable error code

​
Error codes

CodeHTTP StatusDescription
AUTHENTICATION_FAILED401Invalid or missing API key
INSUFFICIENT_BALANCE402Account balance too low (prepaid accounts)
INVALID_REQUEST400Malformed request or invalid parameters
MODEL_NOT_FOUND404Requested model does not exist
MODEL_DISABLED404Model is currently disabled
RATE_LIMITED429Too many requests
ALL_PROVIDERS_EXHAUSTED502All providers failed to handle the request
UPSTREAM_ERRORvariesA provider returned an error

​
Error details

​
AUTHENTICATION_FAILED

Returned when your API key is invalid, missing, or inactive. 
{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "AUTHENTICATION_FAILED"
  }
}
Common causes:
  • Missing Authorization header
  • Malformed authorization header (should be Bearer lmnfl_...)
  • API key has been revoked or is inactive
Resolution: Verify your API key in the Lumenfall dashboard and ensure the Authorization header is correctly formatted.

​
INSUFFICIENT_BALANCE

Returned when your prepaid account balance is too low to cover the request cost. 
{
  "error": {
    "message": "Insufficient balance: $0.05 required, $0.02 available",
    "type": "insufficient_quota",
    "code": "INSUFFICIENT_BALANCE"
  }
}
Resolution: Add credits to your account or enable auto top-up to avoid interruptions. You can also use the ?dryRun=true parameter to estimate costs before making requests.

​
INVALID_REQUEST

Returned when your request is malformed or contains invalid parameters. 
{
  "error": {
    "message": "Invalid parameter: 'size' must be one of 1024x1024, 1536x1024, or 1024x1536",
    "type": "invalid_request_error",
    "code": "INVALID_REQUEST"
  }
}
Common causes:
  • Missing required parameters
  • Invalid parameter values or types
  • Unsupported parameter combinations
Resolution: Review your request against the API documentation and ensure all parameters are valid.

​
MODEL_NOT_FOUND

Returned when the requested model does not exist in the Lumenfall catalog. 
{
  "error": {
    "message": "Model 'nonexistent-model' not found",
    "type": "invalid_request_error",
    "code": "MODEL_NOT_FOUND"
  }
}
Resolution: Check the available models or use the List models endpoint to see all supported models.

​
MODEL_DISABLED

Returned when the requested model exists but is currently disabled. 
{
  "error": {
    "message": "Model 'flux.2-max' is disabled",
    "type": "invalid_request_error",
    "code": "MODEL_DISABLED"
  }
}
Resolution: Choose a different model or check the status page for updates on model availability.

​
RATE_LIMITED

Returned when you’ve exceeded the rate limit. 
{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error",
    "code": "RATE_LIMITED"
  }
}
Resolution: Wait before retrying. Implement exponential backoff in your application to handle rate limits gracefully.

​
ALL_PROVIDERS_EXHAUSTED

Returned when all available providers failed to process your request. This typically indicates a temporary issue with upstream providers. 
{
  "error": {
    "message": "All providers failed",
    "type": "server_error",
    "code": "ALL_PROVIDERS_EXHAUSTED"
  }
}
Resolution: Retry the request after a short delay. If the issue persists, check the status page for provider outages.

​
UPSTREAM_ERROR

Returned when a provider returns an error that cannot be retried. The HTTP status code varies based on the underlying provider error. 
{
  "error": {
    "message": "Content policy violation",
    "type": "invalid_request_error",
    "code": "UPSTREAM_ERROR"
  }
}
Common causes:
  • Content policy violations (prompt or generated content flagged)
  • Provider-specific validation errors
Resolution: Review your prompt for content policy compliance. If you believe this is an error, contact support.

​
Best practices

  • Check HTTP status codes first - Use status codes for high-level error categorization before parsing the response body.
  • Use the code field for programmatic handling - The code field is stable and suitable for conditional logic in your application.
  • Display the message field to users - Error messages are designed to be human-readable and actionable.
  • Implement retry logic with backoff - For 5xx errors and RATE_LIMITED, implement exponential backoff with jitter.