Error Handling

Hướng dẫn xử lý lỗi khi sử dụng Beeknoee AI API.

HTTP Status Codes

Error Response Format

Mọi lỗi trên /v1/* trả về theo khuôn OpenAI:

{
  "error": {
    "message": "Insufficient balance. Need 50,000đ, have 12,000đ. Top up at https://platform.beeknoee.com/billing",
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "params": { "required": 50000, "available": 12000 },
    "request_id": "req_abc123"
  }
}

💡 Lỗi kỹ thuật (nguồn AI gặp sự cố, tham số sai định dạng, timeout…) chỉ có message tiếng Anh và type/code suy từ mã HTTP. Chỉ lỗi nghiệp vụ mới có mã riêng ổn định.

Các loại lỗi thường gặp

1. Authentication Errors (401)

Invalid API Key

{
  "message": "Invalid or revoked API key"
}

Giải pháp:

• Kiểm tra API key có đúng không
• Đảm bảo key bắt đầu bằng sk-bee-
• Kiểm tra không có khoảng trắng thừa
• Kiểm tra key chưa bị thu hồi
• code: "api_key_expired" (401): key đã quá ngày hết hạn — đặt ngày mới ở trang API Keys
• code: "api_key_suspended" (403): key đang tạm ngừng — bấm Kích hoạt lại ở trang API Keys

2. Insufficient Balance (400)

⚠️ Với chat/completions và messages, thiếu tiền không trả lỗi HTTP: API trả HTTP 200 và nội dung trả lời là cảnh báo "⚠️ Số dư tài khoản API không đủ…". Các endpoint khác (embeddings, ảnh, video, audio, rerank, search…) trả 400 như dưới.

{
  "message": "Insufficient balance. Estimated cost: 50.00 VND, Available: 10.00 VND"
}

Giải pháp:

• Nạp thêm tiền vào tài khoản tại platform.beeknoee.com/billing

3. Provider API Errors (400)

{
  "message": "Provider API error: 400 - {\"error\":\"invalid_request\"}"
}

Giải pháp:

• Kiểm tra messages có đúng format không
• Kiểm tra không vượt quá max tokens cho phép

4. Tham số temperature / top_p không hỗ trợ với model Claude (400)

Một số model Claude đời mới không nhận tham số sampling (temperature, top_p, top_k). Nếu bạn gửi kèm, provider trả về lỗi invalid_request_error:

{
  "message": "Provider API error: 400 - temperature is deprecated for this model"
}

hoặc khi gửi đồng thời temperature và top_p:

{
  "message": "Provider API error: 400 - `temperature` and `top_p` cannot both be specified for this model. Please use only one."
}

Model nào bị ảnh hưởng:

Giải pháp:

• Với Opus 4.7+: bỏ hẳn temperature, top_p, top_k khỏi request — model sẽ tự dùng giá trị mặc định.
• Với Sonnet / Haiku 4.x: chỉ truyền một trong temperature (khuyến nghị) hoặc top_p.
• Nếu bạn không truyền các field này thì không bao giờ gặp lỗi trên — đây là cách an toàn nhất.

💡 Beeknoee là proxy trung lập: nếu bạn truyền tham số mà model không hỗ trợ, lỗi từ provider được trả nguyên trạng để bạn tự điều chỉnh — hệ thống không tự ý bỏ tham số của bạn.

5. Model Not Configured (400)

{
  "message": "Model DeepSeek Chat is not configured with provider credentials. Please contact admin."
}

Giải pháp:

• Model chưa được setup API key. Liên hệ admin.

6. Timeout — Cloudflare Error 524

API Error: 524

Cloudflare Error 524: origin_response_timeout
The origin web server did not return a complete response within
the 120-second Proxy Read Timeout window

Nguyên nhân:

• Các model reasoning lớn (Claude Opus, GPT high-reasoning, DeepSeek Reasoning, Gemini Pro, các model "long thinking") đôi khi cần hơn 120 giây để hoàn thành câu trả lời.
• Khi gọi ở chế độ non-streaming (stream: false hoặc không truyền stream), server phải chờ model sinh xong toàn bộ rồi mới trả về một lần. Nếu vượt 120 giây, Cloudflare cắt kết nối và trả lỗi 524.

Giải pháp — gửi lại request với stream: true:

Khi bật streaming, token được trả về liên tục ngay khi model sinh ra → kết nối luôn có dữ liệu → không bao giờ bị 524, kể cả khi model "suy nghĩ" lâu.

from openai import OpenAI

client = OpenAI(
    api_key="sk-bee-your-key",
    base_url="https://platform.beeknoee.com/v1"
)

# ✅ Bật streaming cho model reasoning để tránh lỗi 524
stream = client.chat.completions.create(
    model="claude-opus-4-8",
    messages=[{"role": "user", "content": "Giải bài toán phức tạp..."}],
    stream=True,  # ← bắt buộc cho model phản hồi lâu
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

curl https://platform.beeknoee.com/v1/chat/completions \
  -H "Authorization: Bearer sk-bee-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [{"role": "user", "content": "..."}],
    "stream": true
  }'

💡 Khuyến nghị: Với mọi model reasoning / long-thinking, hãy luôn dùng stream: true. Đây cũng là cách OpenAI và Anthropic khuyến nghị cho các request có thể chạy lâu.

✅ Cập nhật 08/08/2026: Beeknoee đã bổ sung lớp chống 524 cho cả request non-streaming — server nhỏ giọt dữ liệu trong lúc chờ model nên kết nối không còn bị coi là "im lặng". Streaming vẫn là cách tốt nhất (bạn thấy chữ hiện dần thay vì đợi), nhưng stream: false giờ không còn tự động chết ở mốc 120 giây.

7. Stream ended without receiving any events

API Error: Stream ended without receiving any events

Hay gặp nhất trên Claude Code. Nghĩa là kết nối streaming mở thành công nhưng đóng lại mà không có sự kiện nào — bạn gõ lại câu hỏi thì thường chạy bình thường.

Nguyên nhân: một nhà cung cấp phía sau thỉnh thoảng trả về phản hồi rỗng. Trước đây Beeknoee chuyển tiếp nguyên trạng "rỗng" đó cho bạn.

Đã xử lý từ 08/08/2026: khi phát hiện luồng không có sự kiện nào, Beeknoee tự động chuyển sang nhà cung cấp khác ngay trong cùng request — bạn không thấy lỗi nữa. Chỉ khi mọi đường đều hỏng thì mới nhận được thông báo lỗi rõ ràng.

Nếu vẫn gặp:

1. Cập nhật lại cấu hình bằng Quick Setup (bản mới bật streaming toàn phần cho Claude Code)
2. Chạy công cụ Kiểm chứng cấu hình (verify) trong tab Quick Setup
3. Đổi sang model khác để xem lỗi có bám theo một model cụ thể không

8. API returned an empty or malformed response (HTTP 200)

Lỗi này do client (thường là Claude Code) báo, không phải Beeknoee. Nghĩa là có thứ gì đó trả về HTTP 200 nhưng nội dung không phải định dạng API — hay gặp nhất là trang HTML của tường lửa/proxy công ty chen vào giữa.

Kiểm tra: gọi thử bằng curl từ chính máy đó. Nếu nhận về HTML thay vì JSON thì vấn đề nằm ở mạng của bạn, không phải Beeknoee.

curl -s https://platform.beeknoee.com/v1/models \
  -H "Authorization: Bearer sk-bee-your-key" | head -c 200

Kết quả đúng phải bắt đầu bằng {"object":"list" hoặc {"data":[.

9. 403 Forbidden kèm nội dung HTML

Cùng họ với lỗi trên: một tường lửa ứng dụng (WAF) chặn nội dung request trước khi nó tới Beeknoee. Prompt của coding agent thường chứa thẻ dạng XML và mã nguồn — dễ bị luật chống XSS bắt nhầm.

Dấu hiệu nhận biết: curl với câu ngắn thì chạy, nhưng phiên làm việc thật (prompt dài, có code) lại bị chặn.

Cách xử lý: nếu bạn tự dựng proxy/WAF phía trước, hãy miễn kiểm tra nội dung request cho đường dẫn /v1/messages và /v1/chat/completions.

Best Practices

1. Retry với Exponential Backoff

import time
import requests

def call_api_with_retry(payload, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(
                "https://platform.beeknoee.com/v1/chat/completions",
                headers={"Authorization": "Bearer sk-bee-your-key"},
                json=payload
            )
            
            if response.status_code == 200:
                return response.json()
            
            if response.status_code >= 500:
                # Server error - exponential backoff
                time.sleep(2 ** attempt)
                continue
                
            # Client error - don't retry
            response.raise_for_status()
            
        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)
    
    raise Exception("Max retries exceeded")

2. Handle Lỗi Gracefully

def safe_api_call(messages):
    try:
        response = requests.post(
            "https://platform.beeknoee.com/v1/chat/completions",
            headers={"Authorization": "Bearer sk-bee-your-key"},
            json={"messages": messages}
        )
        response.raise_for_status()
        return response.json()
        
    except requests.exceptions.HTTPError as e:
        error = e.response.json()
        message = error.get("message", str(error))
        
        if "Invalid" in message or "Unauthorized" in message:
            print("API key không hợp lệ. Kiểm tra lại key.")
        elif "Insufficient balance" in message:
            print("Hết tiền rồi! Nạp thêm nhé.")
        else:
            print(f"Lỗi: {message}")
            
        return None

3. Sử dụng OpenAI SDK với Error Handling

from openai import OpenAI, APIError, AuthenticationError

client = OpenAI(
    api_key="sk-bee-your-key",
    base_url="https://platform.beeknoee.com/v1"
)

try:
    response = client.chat.completions.create(
        model="deepseek/deepseek-v3.2",
        messages=[{"role": "user", "content": "Hello!"}]
    )
    print(response.choices[0].message.content)
    
except AuthenticationError:
    print("API key không hợp lệ!")
    
except APIError as e:
    print(f"API error: {e.message}")

Liên hệ Support

Nếu gặp lỗi không giải quyết được:

• Email: [email protected]
• Cung cấp: Request ID, timestamp, error message