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

# Errors

> HTTP error codes, mid-stream errors, error response format, and retry strategies for the Cline API.

The Cline API returns errors in a consistent JSON format. HTTP errors come with a non-2xx status code. Mid-stream errors arrive inside the stream body with a `200 OK` status.

## Error response format

All HTTP errors follow the OpenAI error format:

```json theme={null}
{
  "error": {
    "code": 401,
    "message": "Invalid API key",
    "metadata": {}
  }
}
```

<ResponseField name="error.code" type="number | string">
  The HTTP status code, or a string error identifier for mid-stream errors.
</ResponseField>

<ResponseField name="error.message" type="string">
  A human-readable description of what went wrong.
</ResponseField>

<ResponseField name="error.metadata" type="object">
  Additional context such as provider details or internal request IDs.
</ResponseField>

## HTTP error codes

| Code  | Name                  | Cause                                     | What to do                                                 |
| ----- | --------------------- | ----------------------------------------- | ---------------------------------------------------------- |
| `400` | Bad Request           | Malformed JSON, missing required fields   | Check your request body and required parameters            |
| `401` | Unauthorized          | Invalid or missing API key                | Verify the `Authorization` header contains a valid key     |
| `402` | Payment Required      | Insufficient account credits              | Add credits at [app.cline.bot](https://app.cline.bot)      |
| `403` | Forbidden             | Key does not have access to this resource | Check key permissions                                      |
| `404` | Not Found             | Invalid endpoint path or model ID         | Verify the URL and model ID format (`provider/model-name`) |
| `429` | Too Many Requests     | Rate limit exceeded                       | Wait and retry with exponential backoff                    |
| `500` | Internal Server Error | Server-side issue                         | Retry after a short delay                                  |
| `502` | Bad Gateway           | Upstream provider error                   | Retry after a short delay                                  |
| `503` | Service Unavailable   | Service temporarily down                  | Retry after a short delay                                  |

## Mid-stream errors

When streaming, errors can occur after the HTTP response has started. Because the connection is already open with a `200 OK` status, these errors appear as a chunk inside the stream with `finish_reason: "error"`:

```json theme={null}
{
  "choices": [
    {
      "finish_reason": "error",
      "error": {
        "code": "context_length_exceeded",
        "message": "The input exceeds the model's maximum context length."
      }
    }
  ]
}
```

<Warning>
  Mid-stream errors do not produce an HTTP error code. Always check `finish_reason` in your streaming handler — do not assume a `200 OK` status means the request succeeded.
</Warning>

Common mid-stream error codes:

| Code                      | Meaning                                        |
| ------------------------- | ---------------------------------------------- |
| `context_length_exceeded` | Input tokens exceed the model's context window |
| `content_filter`          | Content was blocked by a safety filter         |
| `rate_limit`              | Rate limit hit during generation               |
| `server_error`            | Upstream provider failed during generation     |

## Retry strategies

### When to retry

| Error                       | Retry?  | Strategy                                    |
| --------------------------- | ------- | ------------------------------------------- |
| `400 Bad Request`           | No      | Fix the request                             |
| `401 Unauthorized`          | No      | Fix your API key                            |
| `402 Payment Required`      | No      | Add credits                                 |
| `429 Too Many Requests`     | Yes     | Exponential backoff starting at 1s          |
| `500 Internal Server Error` | Yes     | Retry once after 1s                         |
| `502 Bad Gateway`           | Yes     | Retry up to 3 times with backoff            |
| `503 Service Unavailable`   | Yes     | Retry up to 3 times with backoff            |
| Mid-stream `error`          | Depends | Retry the full request for transient errors |

### Exponential backoff

For transient errors (`429`, `500`, `502`, `503`), retry with exponential backoff to avoid overwhelming the API:

```python theme={null}
import time
import requests

def call_api_with_retry(payload, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(
            "https://api.cline.bot/api/v1/chat/completions",
            headers={
                "Authorization": "Bearer YOUR_API_KEY",
                "Content-Type": "application/json",
            },
            json=payload,
        )

        if response.status_code == 200:
            return response.json()

        if response.status_code in (429, 500, 502, 503):
            delay = (2 ** attempt) + 1
            print(f"Retrying in {delay}s (attempt {attempt + 1}/{max_retries})")
            time.sleep(delay)
            continue

        # Non-retryable error
        response.raise_for_status()

    raise Exception("Max retries exceeded")
```

### Rate limits

If you hit `429` errors frequently:

* Add delays between requests
* Reduce the number of concurrent requests
* Contact support if you need a higher rate limit

## Debugging

When reporting an issue, include the following to help diagnose it faster:

1. The **error code and message** from the response body
2. The **model ID** you were using
3. The **request ID** from the `x-request-id` response header (if present)
4. Whether the error was **immediate** (HTTP error) or **mid-stream** (`finish_reason: "error"`)

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api/authentication">
    Verify your API key is set up correctly.
  </Card>

  <Card title="Chat completions" icon="message" href="/api/chat-completions">
    Review request parameters and response format.
  </Card>
</CardGroup>