# How Lemon AI Handles API Availability Checking Across Multiple LLM Providers

> Learn how Lemon AI checks LLM provider API availability. It sends test requests to the /chat/completions endpoint with an 8s timeout to ensure reliability before production use.

- Repository: [hexdocom/lemonai](https://github.com/hexdocom/lemonai)
- Tags: how-to-guide
- Published: 2026-03-03

---

**Lemon AI validates LLM provider endpoints by sending a minimal test request to the `/chat/completions` endpoint with an 8-second timeout before allowing production use.**

The `hexdocom/lemonai` repository implements a robust **API availability checking** system that ensures every configured LLM provider is reachable and compliant with the OpenAI-compatible chat completions contract. This validation occurs at the utility layer, through a dedicated REST endpoint, and within the frontend setup workflow to prevent misconfigured providers from disrupting conversations.

## The Core Availability Checker Utility

### Implementation in check_llm_api_availability.js

The heart of Lemon AI's availability system resides in [`src/utils/check_llm_api_availability.js`](https://github.com/hexdocom/lemonai/blob/main/src/utils/check_llm_api_availability.js). The exported `checkLlmApiAvailability` function accepts three parameters—`baseUrl`, `apiKey` (optional), and `model`—and constructs a targeted health check.

The utility builds the provider's chat completions URL by appending `/chat/completions` to the `baseUrl`. It then initiates a **POST** request with a minimal payload designed to consume negligible tokens: a prompt of `"hello"`, `max_tokens: 5`, and `enable_thinking: false`. To prevent hanging on offline or slow services, an **AbortController** enforces a hard timeout of **8 seconds**.

Response validation follows strict criteria:

- **HTTP 2xx** with a non-empty `choices` array returns `{ status: true, message: 'LLM API call succeeded.' }`
- **HTTP 2xx** with missing or empty choices returns a failure indicating unexpected response data
- **Non-2xx** status codes return detailed error messages derived from the response body
- **Network or timeout errors** are caught and returned with clear, actionable messages

```javascript
// src/utils/check_llm_api_availability.js
async function checkLlmApiAvailability(baseUrl, apiKey = '', model) {
  // Constructs ${baseUrl}/chat/completions
  // Sends minimal payload: { messages: [{role:'user', content:'hello'}], max_tokens:5, model, enable_thinking:false }
  // AbortController timeout: 8000ms
  // Returns { status: boolean, message: string }
}
module.exports = exports = checkLlmApiAvailability;

```

## Exposing Availability Checks via REST API

### The Platform Router Endpoint

To make the utility accessible to the frontend and external integrations, Lemon AI exposes a public endpoint in [`src/routers/platform/platform.js`](https://github.com/hexdocom/lemonai/blob/main/src/routers/platform/platform.js). The route `POST /api/platform/check_api_availability` acts as a thin wrapper around the core utility.

The router extracts `base_url`, `api_key`, and `model` from the request body, passing them directly to `checkLlmApiAvailability`. The result is then wrapped in the standard Lemon AI success envelope via `response.success`, ensuring consistent API response formatting across the platform.

```javascript
// src/routers/platform/platform.js
router.post("/check_api_availability", async ({ request, response }) => {
  const { base_url, api_key, model } = request.body || {};
  const res = await checkLlmApiAvailability(base_url, api_key, model);
  return response.success(res);
});

```

## Frontend Integration for Provider Validation

### Calling the Endpoint from the UI

The frontend layer consumes this endpoint to provide real-time validation during provider setup. Located in [`frontend/src/services/platforms.js`](https://github.com/hexdocom/lemonai/blob/main/frontend/src/services/platforms.js), the `checkProvider` function (or equivalent service method) constructs a POST request to `/api/platform/check_api_availability`.

The function accepts a configuration object containing `base_url`, `api_key`, and `model`, serializes it as JSON, and parses the response. The UI uses the returned `status` boolean to display success indicators or error messages, preventing users from saving misconfigured providers.

```javascript
// frontend/src/services/platforms.js
export const checkProvider = async (config) => {
  const resp = await fetch('/api/platform/check_api_availability', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(config)   // { base_url, api_key, model }
  });
  return resp.json();   // { data:{ status, message }, code, msg }
};

```

## Why This Design Works for Multi-Provider Support

Lemon AI's **API availability checking** architecture provides three critical advantages for managing diverse LLM providers:

- **Uniform contract validation** – By targeting the OpenAI-compatible `/chat/completions` endpoint, the same utility validates OpenAI, Azure, Anthropic-compatible, and custom providers without protocol-specific logic.
- **Fast feedback loop** – The minimal payload (`"hello"` prompt, 5 max tokens) and 8-second timeout ensure users receive immediate confirmation without wasting tokens or waiting on hung connections.
- **Granular error reporting** – The system distinguishes between network timeouts, HTTP errors, and malformed JSON responses, surfacing specific messages that help users diagnose configuration issues like invalid API keys or incorrect base URLs.

## Summary

- **Core utility**: `checkLlmApiAvailability` in [`src/utils/check_llm_api_availability.js`](https://github.com/hexdocom/lemonai/blob/main/src/utils/check_llm_api_availability.js) performs a minimal POST request to `/chat/completions` with an 8-second timeout.
- **REST endpoint**: `POST /api/platform/check_api_availability` in [`src/routers/platform/platform.js`](https://github.com/hexdocom/lemonai/blob/main/src/routers/platform/platform.js) exposes the utility to clients.
- **Frontend service**: [`frontend/src/services/platforms.js`](https://github.com/hexdocom/lemonai/blob/main/frontend/src/services/platforms.js) calls the endpoint during provider setup to validate configuration before saving.
- **Validation criteria**: HTTP 2xx status plus non-empty `choices` array confirms availability; all other outcomes return detailed error messages.

## Frequently Asked Questions

### What timeout does Lemon AI use for API availability checks?

Lemon AI enforces an **8-second timeout** using an `AbortController` in [`src/utils/check_llm_api_availability.js`](https://github.com/hexdocom/lemonai/blob/main/src/utils/check_llm_api_availability.js). If the LLM provider does not respond within this window, the request is aborted and returns a timeout error message.

### Which HTTP endpoint validates LLM providers in Lemon AI?

The endpoint is `POST /api/platform/check_api_availability`, defined in [`src/routers/platform/platform.js`](https://github.com/hexdocom/lemonai/blob/main/src/routers/platform/platform.js). It accepts a JSON body with `base_url`, `api_key`, and `model`, and returns a status object indicating whether the provider is reachable.

### How does Lemon AI handle timeouts during availability checks?

The system creates an `AbortController` instance and attaches its signal to the fetch request. A `setTimeout` triggers `controller.abort()` after 8,000 milliseconds. If aborted, the catch block returns a structured error indicating the connection timed out, distinguishing it from network or HTTP errors.

### Can Lemon AI verify any OpenAI-compatible API provider?

Yes. The `checkLlmApiAvailability` utility targets the standard OpenAI `/chat/completions` path, making it compatible with any provider implementing that specification—including OpenAI, Azure OpenAI, Anthropic-compatible endpoints, and custom self-hosted models—provided they accept the minimal payload structure used for the health check.