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

# Error Codes

> What went wrong and what to do about it.

## Overview

Errors from Lectr come in two flavours:

* **Proxy errors** — Lectr itself rejected the request before it reached your provider
* **Provider errors** — your provider returned an error, which Lectr forwards in OpenAI format

Both are returned in the same shape so your existing error handling works
regardless of where the error originated.

```json theme={null}
{
  "error": {
    "message": "missing X-Lectr-Key header",
    "type": "authentication_error",
    "code": "missing_lectr_key"
  }
}
```

***

## Proxy errors

These come from Lectr before your provider is ever contacted.

### 401 — Authentication errors

| Code                | Message                        | Fix                                                        |
| ------------------- | ------------------------------ | ---------------------------------------------------------- |
| `missing_lectr_key` | Missing X-Lectr-Key header     | Add `X-Lectr-Key` header to your request                   |
| `invalid_lectr_key` | Invalid or revoked X-Lectr-Key | Check your key in the dashboard — it may have been rotated |
| `org_disabled`      | Organisation is disabled       | Contact support                                            |

***

### 400 — Bad request errors

| Code                   | Message                                   | Fix                                                                |
| ---------------------- | ----------------------------------------- | ------------------------------------------------------------------ |
| `payload_too_large`    | Request body exceeds 2MB limit            | Reduce prompt size or split into smaller requests                  |
| `invalid_provider`     | Unknown value for X-Lectr-Provider        | Use a valid provider: `openai` `anthropic` `groq` `gemini` `azure` |
| `azure_config_missing` | No Azure endpoint configured for this org | Configure your Azure endpoint in Settings → Providers → Azure      |
| `invalid_request`      | Malformed request body                    | Ensure request body is valid JSON with a `model` field             |

***

### 429 — Rate limit errors

| Code                          | Message                                | Fix                                              |
| ----------------------------- | -------------------------------------- | ------------------------------------------------ |
| `rate_limit_exceeded`         | Too many requests                      | Back off and retry — rate limits are per org key |
| `concurrent_streams_exceeded` | Too many concurrent streaming requests | Reduce concurrent stream count                   |

<Note>
  Rate limiting is per org key and per instance. If you're hitting limits
  unexpectedly, check the dashboard for unusual traffic spikes — the anomaly
  detector will surface them.
</Note>

***

### 413 — Payload errors

| Code                | Message                              | Fix                           |
| ------------------- | ------------------------------------ | ----------------------------- |
| `request_too_large` | Request exceeds maximum allowed size | Keep request bodies under 2MB |

***

### 503 — Proxy errors

| Code                   | Message                       | Fix                                        |
| ---------------------- | ----------------------------- | ------------------------------------------ |
| `provider_unreachable` | Could not connect to provider | Check provider status — retry with backoff |

***

## Provider errors

When your provider returns an error, Lectr normalises it to OpenAI format and
forwards it with the original HTTP status code. The `error.type` and `error.code`
reflect the provider's original error.

Common provider errors you'll see:

| Status | Type                    | Typical cause                       |
| ------ | ----------------------- | ----------------------------------- |
| `401`  | `authentication_error`  | Invalid or expired provider API key |
| `429`  | `rate_limit_error`      | Provider rate limit hit             |
| `400`  | `invalid_request_error` | Invalid model name, bad parameters  |
| `500`  | `server_error`          | Provider internal error             |
| `503`  | `service_unavailable`   | Provider outage                     |

### Identifying error source

The dashboard attributes errors to their source — proxy or provider — so you
can tell at a glance whether the issue is with Lectr or with your provider.

The `Recent Failures` table shows:

| Request ID  | Model         | Latency | Status         |
| ----------- | ------------- | ------: | -------------- |
| ed3f80fa... | `gpt-4o-mini` |   101ms | `openai_error` |
| 10405cb9... | `gpt-4o`      |    96ms | `openai_error` |
| 3e9db15f... | `gpt-4o`      |       — | `proxy_error`  |

`proxy_error` means Lectr rejected it. Everything else means the provider did.

***

## Error handling in code

Provider errors pass through in OpenAI SDK format — your existing error handling
works unchanged.

<CodeGroup>
  ```typescript Node.js theme={null}
  import OpenAI, { APIError } from "openai";

  try {
    const response = await client.chat.completions.create({ ... });
  } catch (err) {
    if (err instanceof APIError) {
      console.error(err.status);   // HTTP status
      console.error(err.message);  // error message
      console.error(err.code);     // error code
    }
  }
  ```

  ```python Python theme={null}
  from openai import APIError

  try:
      response = client.chat.completions.create(...)
  except APIError as e:
      print(e.status_code)  # HTTP status
      print(e.message)      # error message
      print(e.code)         # error code
  ```
</CodeGroup>

***

## Retrying errors

Not all errors are worth retrying. A quick guide:

| Status | Retry? | Notes                                              |
| ------ | ------ | -------------------------------------------------- |
| `400`  | No     | Fix the request first                              |
| `401`  | No     | Fix your API key                                   |
| `413`  | No     | Reduce payload size                                |
| `429`  | Yes    | Exponential backoff — wait before retrying         |
| `500`  | Yes    | Retry once — if it persists, check provider status |
| `503`  | Yes    | Retry with backoff — likely a provider outage      |

For `429` errors, start with a 1 second delay and double on each retry up to
a maximum of 60 seconds.