> ## Documentation Index
> Fetch the complete documentation index at: https://docs.llmgrid.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Common Error Messages

This page lists common errors you may encounter when calling LLMGrid’s API and how to resolve them quickly.

**Base URL:** `https://api.llmgrid.ai/v1`\
**Auth Header:** `Authorization: Bearer <LLMGRID_API_KEY>`

## Quick Triage

Use the status code to decide your next step:

* **4xx (except 429)** → request issue (auth, permissions, invalid params). Fix the request.
* **429** → throttling / quota / budget issue. Back off, retry, and/or reduce throughput.
* **5xx** → transient failure (gateway or upstream provider). Retry with backoff.

## 400 — Bad Request

### What it means

The request payload is invalid or contains unsupported parameters.

### Common causes

* Invalid JSON (malformed body)
* Wrong parameter names or types (e.g., string where number expected)
* Unsupported parameter for the selected model/provider
* Invalid `messages` structure (missing `role` or `content`)

### How to fix

* Validate your JSON and parameter types.
* Remove provider-unsupported params, or enable “drop unsupported params” if your SDK supports it.
* Ensure `messages` is an array of objects with `role` + `content`.

## 401 — Unauthorized

### What it means

Missing or invalid API key.

### Common causes

* Missing `Authorization` header
* Wrong key format
* Expired/revoked Virtual Key

### How to fix

* Set `Authorization: Bearer $LLMGRID_API_KEY`
* Regenerate/rotate the Virtual Key if needed.

## 403 — Forbidden

### What it means

You are authenticated, but not authorized to perform the requested action.

### Common causes

* Virtual Key does not have access to the model/provider
* Tenant policy blocks the request
* Environment restrictions (e.g., IP allowlist, security policy)

### How to fix

* Confirm the Virtual Key is assigned permissions for the model/provider.
* Check tenant-level policies and access controls.

## 404 — Not Found

### What it means

The endpoint or resource does not exist.

### Common causes

* Wrong base URL or path
* Incorrect endpoint (`/chat/completion` vs `/chat/completions`)
* Invalid model name (or model not enabled for your tenant)

### How to fix

* Confirm base URL: `https://api.llmgrid.ai/v1`
* Confirm endpoint path and model name spelling.

## 409 — Conflict

### What it means

The request conflicts with the current state of the resource.

### Common causes

* Attempting to create a resource that already exists
* Concurrent updates to the same configuration/key

### How to fix

* Retry if the operation is safe and idempotent.
* Resolve duplicates (use “update” instead of “create” where applicable).

## 422 — Unprocessable Entity

### What it means

The request is syntactically valid JSON, but fails schema/validation rules.

### Common causes

* Tool/function schema invalid (missing required fields)
* Message format values invalid (unsupported role/content structure)
* Parameter values out of range (e.g., `top_p` not between 0 and 1)

### How to fix

* Validate tool definitions and message objects.
* Check parameter bounds and supported values for the chosen model/provider.

## 429 — Too Many Requests (Rate Limit / Quota / Budget)

### What it means

You are sending too many requests and/or tokens, or you exceeded allowed quotas/budgets.

### Common causes

* Burst traffic (RPM/TPM exceeded)
* Concurrency too high
* Quota/budget limits reached (tenant/project/key)

### How to fix

* Implement retries with exponential backoff + jitter.
* Add client-side throttling (queue + concurrency limits).
* Reduce `max_tokens` or request frequency.
* Verify budgets and rate limit settings in LLMGrid.

## 500 — Internal Server Error

### What it means

A server-side error occurred (gateway or upstream provider).

### Common causes

* Transient provider instability
* Temporary routing issues
* Internal service errors

### How to fix

* Retry with backoff.
* If persistent, log request context (model, time, tenant/key) and contact support.

## 503 — Service Unavailable

### What it means

The service is temporarily unavailable or overloaded.

### Common causes

* Provider overload
* Temporary maintenance window
* Capacity constraints during high traffic

### How to fix

* Retry with longer backoff than for 500s.
* Reduce concurrency and request rate.
* Use fallbacks if configured.

## Timeouts / Connection Errors

### Symptoms

* Requests hang, then fail
* Streaming disconnects mid-response

### Common causes

* Network instability
* Too-low client timeout for long generations
* Very large prompts / high `max_tokens`