The Cline API returns errors in a consistent JSON format. Understanding these errors helps you build reliable integrations.
All errors follow the OpenAI error format:
{
"error": {
"code": 401,
"message": "Invalid API key",
"metadata": {}
}
}
| Field | Type | Description |
|---|
code | number/string | HTTP status code or error identifier |
message | string | Human-readable description of the error |
metadata | object | Additional context (provider details, request IDs) |
Error Codes
HTTP Errors
These are returned as the HTTP response status code and in the error body:
| Code | Name | Cause | What to do |
|---|
400 | Bad Request | Malformed request body, missing required fields | Check your JSON syntax and required parameters |
401 | Unauthorized | Invalid or missing API key | Verify your API key in the Authorization header |
402 | Payment Required | Insufficient 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 or model ID | Verify the URL and model ID format |
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 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."
}
}
]
}
| 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 |
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
| Error | Retry? | Strategy |
|---|
401 Unauthorized | No | Fix your API key |
402 Payment Required | No | Add credits |
429 Too Many Requests | Yes | Exponential backoff (start 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 |
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:
- The error code and message from the response
- The model ID you were using
- The request ID (from the
x-request-id response header, if available)
- Whether the error was immediate (HTTP error) or mid-stream (finish_reason error)
