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:

{
  "error": {
    "code": 401,
    "message": "Invalid API key",
    "metadata": {}
  }
}

error.code · number | string

The HTTP status code, or a string error identifier for mid-stream errors.

error.message · string

A human-readable description of what went wrong.

error.metadata · object

Additional context such as provider details or internal request IDs.

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
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":

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

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.

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:

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")

Authentication

Verify your API key is set up correctly.

Chat completions

Review request parameters and response format.