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

# Troubleshooting

> Fix common LLM.kiwi issues: 401 authentication failures, malformed requests, connection timeouts, SDK configuration errors, and broken streaming responses.

Begin with this minimal check to separate account or network problems from bugs in your application code.

```bash theme={null}
curl "https://api.llm.kiwi/v1/models" \
  -H "Authorization: Bearer $LLM_KIWI_API_KEY"
```

If it returns a model list, your base URL, network connection, and key are working.

## Quick diagnosis

| Symptom                       | Check first                                        |
| ----------------------------- | -------------------------------------------------- |
| `401 Unauthorized`            | API key and `Bearer ` prefix                       |
| `400 Bad Request`             | JSON syntax, `model`, and `messages`               |
| `404 Not Found`               | Base URL and endpoint path                         |
| `429 Too Many Requests`       | Request frequency and retry loop                   |
| Timeout or connection error   | HTTPS URL, DNS, firewall, and service availability |
| Works in cURL but not the SDK | SDK `base_url` / `baseURL` setting                 |
| No visible streaming text     | `stream: true` and chunk iteration                 |

## 401: unauthorized

Use exactly this header shape:

```http theme={null}
Authorization: Bearer sk_kiwi_...
```

Check that:

* There is one space after `Bearer`.
* The key was copied completely with no quotes or trailing whitespace.
* The key has not been revoked.
* Your environment variable is available to the running process.

<Tabs>
  <Tab title="macOS and Linux">
    Confirm only that a value exists without printing the secret:

    ```bash theme={null}
    test -n "$LLM_KIWI_API_KEY" && echo "Key is set" || echo "Key is missing"
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell theme={null}
    if ($env:LLM_KIWI_API_KEY) { "Key is set" } else { "Key is missing" }
    ```
  </Tab>
</Tabs>

If needed, revoke the old key and create a new one in the [dashboard](https://llm.kiwi/dashboard).

## 400: bad request

A minimal valid body is:

```json theme={null}
{
  "model": "auto",
  "messages": [
    {"role": "user", "content": "Hello!"}
  ]
}
```

Common mistakes:

* Single quotes or missing commas in JSON
* `messages` sent as an object instead of an array
* Missing `role` or `content`
* Unsupported model value
* Sending a JSON string inside another JSON object
* Forgetting `Content-Type: application/json`

Compare your request with the [API reference](/api-reference#create-a-chat-completion).

## 404: not found

Use:

```text theme={null}
https://api.llm.kiwi/v1
```

With an SDK, the base URL ends at `/v1`:

```python theme={null}
client = OpenAI(base_url="https://api.llm.kiwi/v1", api_key=key)
```

With direct HTTP, add the endpoint:

```text theme={null}
https://api.llm.kiwi/v1/chat/completions
```

Do not add `/v1` twice.

## 429: rate limited

Wait before retrying. Repeated immediate retries make the problem worse.

* Respect `Retry-After` when present.
* Use exponential backoff and a small random delay.
* Limit concurrency in loops and background jobs.
* Stop after a small number of failed attempts.

See [Limits and pricing](/limits#rate-limits) for an example.

## Timeout or connection failure

1. Confirm the URL begins with `https://`.
2. Run the model-list cURL check from the same machine.
3. Check whether a proxy, VPN, firewall, or hosting provider blocks outbound HTTPS.
4. Set a reasonable client timeout such as 30 seconds.
5. Retry temporary failures a limited number of times.

A connection error means no valid HTTP response was received. A `500` or `503` means the API did respond but could not complete the request.

## SDK uses the wrong service

The most common configuration error is forgetting the custom base URL.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    client = OpenAI(
        base_url="https://api.llm.kiwi/v1",
        api_key=os.environ["LLM_KIWI_API_KEY"],
    )
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const client = new OpenAI({
      baseURL: "https://api.llm.kiwi/v1",
      apiKey: process.env.LLM_KIWI_API_KEY,
    });
    ```
  </Tab>
</Tabs>

Note the naming difference: Python uses `base_url`; JavaScript uses `baseURL`.

## Streaming shows nothing

Confirm all three conditions:

1. The request includes `stream: true`.
2. Your code iterates over chunks instead of waiting for a normal completion object.
3. Your terminal or web server flushes output instead of buffering it.

Begin with an SDK streaming example from [Code examples](/examples#stream-a-response) before implementing raw SSE parsing.

## Before contacting support

Collect:

* Approximate time of the failed request and your timezone
* HTTP status code
* Error `type`, `code`, and message
* Endpoint and SDK name/version
* A minimal request with private data removed

<Warning>
  Never send your full API key. Redact it as `sk_kiwi_...last4`.
</Warning>

<CardGroup cols={2}>
  <Card title="Contact support" icon="envelope" href="mailto:support@llm.kiwi">
    Email [support@llm.kiwi](mailto:support@llm.kiwi) with the safe diagnostic details above.
  </Card>

  <Card title="Error reference" icon="triangle-exclamation" href="/errors">
    Look up status-specific behavior.
  </Card>
</CardGroup>