Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cline.bot/llms.txt

Use this file to discover all available pages before exploring further.

The Cline API returns errors in a consistent JSON format. Understanding these errors helps you build reliable integrations.

​
Error Format

All errors follow the OpenAI error format: 
{
  "error": {
    "code": 401,
    "message": "Invalid API key",
    "metadata": {}
  }
}
FieldTypeDescription
codenumber/stringHTTP status code or error identifier
messagestringHuman-readable description of the error
metadataobjectAdditional context (provider details, request IDs)

​
Error Codes

​
HTTP Errors

These are returned as the HTTP response status code and in the error body:
CodeNameCauseWhat to do
400Bad RequestMalformed request body, missing required fieldsCheck your JSON syntax and required parameters
401UnauthorizedInvalid or missing API keyVerify your API key in the Authorization header
402Payment RequiredInsufficient creditsAdd credits at app.cline.bot
403ForbiddenKey does not have access to this resourceCheck key permissions
404Not FoundInvalid endpoint or model IDVerify the URL and model ID format
429Too Many RequestsRate limit exceededWait and retry with exponential backoff
500Internal Server ErrorServer-side issueRetry after a short delay
502Bad GatewayUpstream provider errorRetry after a short delay
503Service UnavailableService temporarily downRetry after a short delay

​
Mid-Stream Errors

When streaming, errors can occur after the response has started. These appear as a chunk with finish_reason: "error": 
{
  "choices": [
    {
      "finish_reason": "error",
      "error": {
        "code": "context_length_exceeded",
        "message": "The input exceeds the model's maximum context length."
      }
    }
  ]
}
Common mid-stream error codes:
CodeMeaning
context_length_exceededInput tokens exceed the model’s context window
content_filterContent was blocked by a safety filter
rate_limitRate limit hit during generation
server_errorUpstream provider failed during generation
Mid-stream errors do not produce an HTTP error code (the connection was already 200 OK). Always check finish_reason in your streaming handler.

​
Retry Strategies

​
Exponential Backoff

For transient errors (429, 500, 502, 503), retry with exponential backoff: 
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")

​
When to Retry

ErrorRetry?Strategy
401 UnauthorizedNoFix your API key
402 Payment RequiredNoAdd credits
429 Too Many RequestsYesExponential backoff (start at 1s)
500 Internal Server ErrorYesRetry once after 1s
502 Bad GatewayYesRetry up to 3 times with backoff
503 Service UnavailableYesRetry up to 3 times with backoff
Mid-stream errorDependsRetry the full request for transient errors

​
Rate Limits

If you hit rate limits frequently:
  • Add delays between requests
  • Reduce the number of concurrent requests
  • Contact support if you need higher limits

​
Debugging

When reporting issues, include:
  1. The error code and message from the response
  2. The model ID you were using
  3. The request ID (from the x-request-id response header, if available)
  4. Whether the error was immediate (HTTP error) or mid-stream (finish_reason error)

Chat Completions

Endpoint reference with request and response schemas.

Authentication

Verify your API key is configured correctly.