Api Errors

+++ disableToc = false title = "API Error Reference" weight = 26 +++

This page documents the error responses returned by the LocalAI API. LocalAI supports multiple API formats (OpenAI, Anthropic, Open Responses), each with its own error structure.

{{% notice note %}} For backend and runtime failure messages (a model that will not load, could not load model, grpc service not ready, SIGILL, VRAM out of memory, the model-load cooldown 503), rather than API-envelope errors, see {{% relref "reference/runtime-errors" %}}. {{% /notice %}}

Error Response Formats

OpenAI-Compatible Format

Most endpoints return errors using the OpenAI-compatible format:

{
  "error": {
    "code": 400,
    "message": "A human-readable description of the error",
    "type": "invalid_request_error",
    "param": null
  }
}

This format is used by: /v1/chat/completions, /v1/completions, /v1/embeddings, /v1/images/generations, /v1/audio/transcriptions, /models, and other OpenAI-compatible endpoints.

Anthropic Format

The /v1/messages endpoint returns errors in Anthropic's format:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "A human-readable description of the error"
  }
}

Open Responses Format

The /v1/responses endpoint returns errors with this structure:

{
  "error": {
    "type": "invalid_request",
    "message": "A human-readable description of the error",
    "code": "",
    "param": "parameter_name"
  }
}

HTTP Status Codes

Global Error Handling

Authentication Errors (401)

When authentication is enabled - either via API keys (LOCALAI_API_KEY) or the user auth system (LOCALAI_AUTH=true) - API requests must include valid credentials. Credentials can be provided through:

• Authorization: Bearer <key> header (API key, user API key, or session ID)
• x-api-key: <key> header
• xi-api-key: <key> header
• session cookie (user auth sessions)
• token cookie (legacy API keys)

Authorization Errors (403)

When user authentication is enabled, admin-only endpoints (model management, system settings, traces, agents, etc.) return 403 if accessed by a non-admin user. See [Authentication & Authorization]({{%relref "features/authentication" %}}) for the full list of admin-only endpoints.

Example request without a key:

curl http://localhost:8080/v1/models \
  -H "Content-Type: application/json"

Error response:

{
  "error": {
    "code": 401,
    "message": "An authentication key is required",
    "type": "invalid_request_error"
  }
}

The response also includes the header WWW-Authenticate: Bearer.

Request Parsing Errors (400)

All endpoints return a 400 error if the request body cannot be parsed:

{
  "error": {
    "code": 400,
    "message": "failed parsing request body: <details>",
    "type": ""
  }
}

Not Found (404)

Requests to undefined routes return:

{
  "error": {
    "code": 404,
    "message": "Resource not found"
  }
}

Opaque Errors Mode

When LOCALAI_OPAQUE_ERRORS=true is set, all error responses return an empty body with only the HTTP status code. This is a security hardening option that prevents information leaks.

Per-Endpoint Error Scenarios

Chat Completions - POST /v1/chat/completions

# Missing model field
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "hello"}]}'

See also: [Text Generation]({{%relref "features/text-generation" %}})

Completions - POST /v1/completions

Embeddings - POST /v1/embeddings

See also: [Embeddings]({{%relref "features/embeddings" %}})

Image Generation - POST /v1/images/generations

See also: [Image Generation]({{%relref "features/image-generation" %}})

Image Editing (Inpainting) - POST /v1/images/edits

Audio Transcription - POST /v1/audio/transcriptions

See also: [Audio to Text]({{%relref "features/audio-to-text" %}})

Text to Speech - POST /v1/audio/speech, POST /tts

See also: [Text to Audio]({{%relref "features/text-to-audio" %}})

ElevenLabs TTS - POST /v1/text-to-speech/:voice-id

ElevenLabs Sound Generation - POST /v1/sound-generation

Reranking - POST /v1/rerank, POST /jina/v1/rerank

See also: [Reranker]({{%relref "features/reranker" %}})

Anthropic Messages - POST /v1/messages

# Missing model field
curl http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "hello"}], "max_tokens": 100}'

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "model is required"
  }
}

Open Responses - POST /v1/responses

# Missing model field
curl http://localhost:8080/v1/responses \
  -H "Content-Type: application/json" \
  -d '{"input": "hello"}'

{
  "error": {
    "type": "invalid_request",
    "message": "model is required",
    "code": "",
    "param": ""
  }
}

Open Responses - GET /v1/responses/:id

Open Responses Events - GET /v1/responses/:id/events

Object Detection - POST /v1/detection

See also: [Object Detection]({{%relref "features/object-detection" %}})

Video Generation - POST /v1/video/generations

Voice Activity Detection - POST /v1/audio/vad

Tokenize - POST /v1/tokenize

Models - GET /v1/models, GET /models

See also: [Model Gallery]({{%relref "features/model-gallery" %}})

Handling Errors in Client Code

Python (OpenAI SDK)

from openai import OpenAI, APIError

client = OpenAI(base_url="http://localhost:8080/v1", api_key="your-key")

try:
    response = client.chat.completions.create(
        model="my-model",
        messages=[{"role": "user", "content": "hello"}],
    )
except APIError as e:
    print(f"Status: {e.status_code}, Message: {e.message}")

curl

# Check HTTP status code
response=$(curl -s -w "\n%{http_code}" http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "nonexistent", "messages": [{"role": "user", "content": "hi"}]}')

http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | head -1)

if [ "$http_code" -ne 200 ]; then
  echo "Error $http_code: $body"
fi

Related Configuration