Errors & Rate Limits

Understand failure modes so you can retry safely and surface clear messages to users.

Error envelope

{
  "success": false,
  "error": "Error message",
  "details": {
    "tokensRequired": 120,
    "remainingTokens": 40
  }
}

details is optional and varies by error type.

HTTP status codes

Status	Meaning	Typical cause
200	Success	Request completed
400	Bad Request	Missing prompt/model/input, unsupported type, stream not allowed
401	Unauthorized	Missing, invalid, or expired API key
402	Payment Required	No active subscription/credit or insufficient tokens
403	Forbidden	Provider/model not allowed for this key
413	Payload Too Large	Prompt/messages exceed platform limits
429	Too Many Requests	Hourly rate limit or IP throttle exceeded
500	Server Error	Unexpected failure during generation
503	Unavailable	Pricing/config temporarily unavailable

Common error messages

Missing API key

{
  "success": false,
  "error": "API key is required. Please provide it in X-API-Key header or Authorization header."
}

Invalid API key format

{
  "success": false,
  "error": "Invalid API key format",
  "details": {
    "isExpired": false,
    "isProviderAllowed": true,
    "isModelAllowed": true,
    "isRateLimited": false
  }
}

Invalid parameters

{
  "success": false,
  "error": "Prompt is required and must be a string"
}

{
  "success": false,
  "error": "Model is required and must be a string"
}

{
  "success": false,
  "error": "Model not found or unavailable"
}

{
  "success": false,
  "error": "Field \"input\" is required for embedding requests (string or array of strings)"
}

Insufficient tokens

{
  "success": false,
  "error": "Insufficient tokens for this operation",
  "details": {
    "tokensRequired": 500,
    "remainingTokens": 120
  }
}

No subscription / credit

{
  "success": false,
  "error": "No active subscription found. Please purchase a subscription to use this service."
}

Rate limited key

{
  "success": false,
  "error": "Rate limit exceeded",
  "details": {
    "isRateLimited": true,
    "remainingHourlyRequests": 0
  }
}

Rate limits

Each API key can define rate_limit_per_hour and max_tokens_per_request.

Inspect live values via GET https://ai.lumowp.com/api/external/ai:

Field	Description
api_key_info.rate_limit_per_hour	Max requests per hour
api_key_info.remaining_hourly_requests	Remaining requests in the current window
api_key_info.max_tokens_per_request	Max completion (reply) tokens per text call
limits.*	Platform prompt/message/embedding caps

There is also a shared per-IP throttle on the External API.

Retry guidance

Status	Retry?	Strategy
429	Yes	Exponential backoff; respect hourly window
500 / 503	Yes	Retry with jitter; fail after a few attempts
400 / 401 / 403	No	Fix request or key configuration
402	No	Top up credits/tokens or renew subscription
413	No	Shorten prompt/messages/input

Client-side pattern

async function callExternalAI(body, apiKey) {
  const res = await fetch("https://ai.lumowp.com/api/external/ai", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": apiKey
    },
    body: JSON.stringify(body)
  })

  const json = await res.json()

  if (!res.ok || !json.success) {
    const error = new Error(json.error || "Request failed")
    error.status = res.status
    error.details = json.details
    throw error
  }

  return json.data
}